Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: 实现 commit、restore、show 文件系统多版本管理功能 (#2756)
Haoyu Zhangaa53e7aede01
diff --git a/Cargo.lock b/Cargo.lockindex bc4e97b81..8ebae849a 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1492,6 +1492,19 @@ dependencies = ["syn",]+[[package]]+name = "dashmap"+version = "5.5.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "978747c1d849a7d2ee5e8adc0159961c48fb7e5db2f06af6723b80123bb53856"+dependencies = [+ "cfg-if",+ "hashbrown 0.14.5",+ "lock_api",+ "once_cell",+ "parking_lot_core",+]+[[package]]name = "deflate64"version = "0.1.11"@@ -1788,6 +1801,12 @@ version = "0.1.9"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"+[[package]]+name = "faster-hex"+version = "0.9.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a2a2b11eda1d40935b26cf18f6833c526845ae8c41e58d09af6adeb6f0269183"+[[package]]name = "fastrand"version = "2.3.0"@@ -2053,6 +2072,102 @@ dependencies = ["weezl",]+[[package]]+name = "gix-actor"+version = "0.31.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a0e454357e34b833cc3a00b6efbbd3dd4d18b24b9fb0c023876ec2645e8aa3f2"+dependencies = [+ "bstr",+ "gix-date",+ "gix-utils",+ "itoa",+ "thiserror 1.0.69",+ "winnow 0.6.26",+]++[[package]]+name = "gix-date"+version = "0.8.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9eed6931f21491ee0aeb922751bd7ec97b4b2fe8fbfedcb678e2a2dce5f3b8c0"+dependencies = [+ "bstr",+ "itoa",+ "thiserror 1.0.69",+ "time",+]++[[package]]+name = "gix-features"+version = "0.38.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ac7045ac9fe5f9c727f38799d002a7ed3583cd777e3322a7c4b43e3cf437dc69"+dependencies = [+ "flate2",+ "gix-hash",+ "gix-trace",+ "libc",+ "prodash",+ "sha1_smol",+ "thiserror 1.0.69",+]++[[package]]+name = "gix-hash"+version = "0.14.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f93d7df7366121b5018f947a04d37f034717e113dcf9ccd85c34b58e57a74d5e"+dependencies = [+ "faster-hex",+ "thiserror 1.0.69",+]++[[package]]+name = "gix-object"+version = "0.42.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "25da2f46b4e7c2fa7b413ce4dffb87f69eaf89c2057e386491f4c55cadbfe386"+dependencies = [+ "bstr",+ "gix-actor",+ "gix-date",+ "gix-features",+ "gix-hash",+ "gix-utils",+ "gix-validate",+ "itoa",+ "smallvec",+ "thiserror 1.0.69",+ "winnow 0.6.26",+]++[[package]]+name = "gix-trace"+version = "0.1.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "44dc45eae785c0eb14173e0f152e6e224dcf4d45b6a6999a3aed22af541ad678"++[[package]]+name = "gix-utils"+version = "0.1.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ff08f24e03ac8916c478c8419d7d3c33393da9bb41fa4c24455d5406aeefd35f"+dependencies = [+ "fastrand",+ "unicode-normalization",+]++[[package]]+name = "gix-validate"+version = "0.8.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "82c27dd34a49b1addf193c92070bcbf3beaf6e10f16a78544de6372e146a0acf"+dependencies = [+ "bstr",+ "thiserror 1.0.69",+]+[[package]]name = "globset"version = "0.4.18"@@ -3230,6 +3345,15 @@ dependencies = ["libm",]+[[package]]+name = "num_threads"+version = "0.1.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5c7398b9c8b70908f6371f47ed36737907c87c52af34c268fed0bf0ceb92ead9"+dependencies = [+ "libc",+]+[[package]]name = "once_cell"version = "1.21.3"@@ -3548,6 +3672,12 @@ dependencies = ["unicode-ident",]+[[package]]+name = "prodash"+version = "28.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "744a264d26b88a6a7e37cbad97953fa233b94d585236310bcbc88474b4092d79"+[[package]]name = "profiling"version = "1.0.18"@@ -3748,7 +3878,14 @@ dependencies = ["bytes","chrono","criterion",+ "dashmap",+ "flate2","futures",+ "gix-actor",+ "gix-date",+ "gix-features",+ "gix-hash",+ "gix-object","grep","grep-matcher","grep-regex",@@ -3769,6 +3906,7 @@ dependencies = ["tempfile","thiserror 1.0.69","tokio",+ "toml","tracing","uuid",]@@ -3790,11 +3928,15 @@ dependencies = [name = "ragfs-python"version = "0.1.0"dependencies = [+ "bytes",+ "gix-hash","pyo3","ragfs","ragfs-cache-redis",+ "serde","serde_json","tokio",+ "toml",][[package]]@@ -4408,6 +4550,15 @@ dependencies = ["zmij",]+[[package]]+name = "serde_spanned"+version = "0.6.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"+dependencies = [+ "serde",+]+[[package]]name = "serde_urlencoded"version = "0.7.1"@@ -4984,7 +5135,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"dependencies = ["deranged",+ "itoa",+ "libc","num-conv",+ "num_threads","powerfmt","serde_core","time-core",@@ -5114,6 +5268,47 @@ dependencies = ["tokio",]+[[package]]+name = "toml"+version = "0.8.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"+dependencies = [+ "serde",+ "serde_spanned",+ "toml_datetime",+ "toml_edit",+]++[[package]]+name = "toml_datetime"+version = "0.6.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"+dependencies = [+ "serde",+]++[[package]]+name = "toml_edit"+version = "0.22.27"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"+dependencies = [+ "indexmap",+ "serde",+ "serde_spanned",+ "toml_datetime",+ "toml_write",+ "winnow 0.7.15",+]++[[package]]+name = "toml_write"+version = "0.1.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"+[[package]]name = "tower"version = "0.5.3"@@ -5916,6 +6111,24 @@ version = "0.53.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"+[[package]]+name = "winnow"+version = "0.6.26"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1e90edd2ac1aa278a5c4599b1d89cf03074b610800f866d4026dc199d7929a28"+dependencies = [+ "memchr",+]++[[package]]+name = "winnow"+version = "0.7.15"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"+dependencies = [+ "memchr",+]+[[package]]name = "wit-bindgen"version = "0.51.0"diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 63b87e47f..90e7d99ca 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -33,6 +33,38 @@ fn compact_request_body(body: &mut Value) {});}+#[derive(serde::Serialize)]+pub struct SnapshotCommitReq {+ pub message: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub paths: Option<Vec<String>>,+ pub branch: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub author_name: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub author_email: Option<String>,+}++#[derive(serde::Serialize)]+pub struct SnapshotRestoreReq {+ #[serde(skip_serializing_if = "Option::is_none")]+ pub project_dir: Option<String>,+ pub source_commit: String,+ pub branch: String,+ pub dry_run: bool,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub message: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub author_name: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub author_email: Option<String>,+}++pub enum SnapshotShowResult {+ Metadata(Value),+ Blob { oid: String, size: u64, bytes: Vec<u8> },+}+// ============ HttpClient ============/// High-level HTTP client for OpenViking API@@ -1448,6 +1480,108 @@ impl HttpClient {self.post_with_query("/api/v1/watches/trigger", &empty, ¶ms).await}++ // ============= Snapshot =============++ pub async fn snapshot_commit(&self, req: &SnapshotCommitReq) -> Result<Value> {+ self.post("/api/v1/snapshot/commit", req).await+ }++ pub async fn snapshot_restore(&self, req: &SnapshotRestoreReq) -> Result<Value> {+ self.post("/api/v1/snapshot/restore", req).await+ }++ pub async fn snapshot_log(&self, branch: &str, limit: u32) -> Result<Value> {+ let params = vec![+ ("branch".to_string(), branch.to_string()),+ ("limit".to_string(), limit.to_string()),+ ];+ self.get("/api/v1/snapshot/log", ¶ms).await+ }++ pub async fn snapshot_show(+ &self,+ target_ref: &str,+ path: Option<&str>,+ ) -> Result<SnapshotShowResult> {+ let url = format!("{}/api/v1/snapshot/show", self.base.base_url);+ let mut query: Vec<(String, String)> = vec![("target_ref".to_string(), target_ref.to_string())];+ if let Some(p) = path {+ query.push(("path".to_string(), p.to_string()));+ }++ let response = self+ .base+ .http+ .get(&url)+ .headers(self.base.build_headers())+ .query(&query)+ .send()+ .await+ .map_err(|e| Error::Network(format!("HTTP request failed: {}", e)))?;++ let status = response.status();+ let content_type = response+ .headers()+ .get(reqwest::header::CONTENT_TYPE)+ .and_then(|v| v.to_str().ok())+ .unwrap_or("")+ .to_string();++ if path.is_some() && status.is_success() && content_type.starts_with("application/octet-stream") {+ let oid = response+ .headers()+ .get("x-snapshot-oid")+ .and_then(|v| v.to_str().ok())+ .unwrap_or("")+ .to_string();+ let size: u64 = response+ .headers()+ .get("x-snapshot-size")+ .and_then(|v| v.to_str().ok())+ .and_then(|s| s.parse().ok())+ .unwrap_or(0);+ let bytes = response+ .bytes()+ .await+ .map_err(|e| Error::Network(format!("Failed to read blob bytes: {}", e)))?+ .to_vec();+ return Ok(SnapshotShowResult::Blob { oid, size, bytes });+ }++ let bytes = response+ .bytes()+ .await+ .map_err(|e| Error::Network(format!("Failed to read response body: {}", e)))?;+ let json: Value = match serde_json::from_slice(&bytes) {+ Ok(v) => v,+ Err(e) => {+ let body_str = String::from_utf8_lossy(&bytes);+ return Err(Error::Network(format!(+ "Failed to parse JSON response: {}\n\nRaw response body:\n{}",+ e, body_str+ )));+ }+ };++ if !status.is_success() {+ return Err(Error::api_with_status(+ crate::base_client::api_error_from_envelope(&json, status),+ status.as_u16(),+ ));+ }+ if let Some(error) = json.get("error") {+ if !error.is_null() {+ return Err(Error::api_with_status(+ crate::base_client::api_error_from_envelope(&json, status),+ status.as_u16(),+ ));+ }+ }++ let result = json.get("result").cloned().unwrap_or(Value::Null);+ Ok(SnapshotShowResult::Metadata(result))+ }}#[cfg(test)]diff --git a/crates/ov_cli/src/commands/mod.rs b/crates/ov_cli/src/commands/mod.rsindex 3673431b6..fa7866f93 100644--- a/crates/ov_cli/src/commands/mod.rs+++ b/crates/ov_cli/src/commands/mod.rs@@ -13,5 +13,6 @@ pub mod search;pub mod session;pub mod skills;pub mod system;+pub mod snapshot;pub mod task;pub mod watch;diff --git a/crates/ov_cli/src/commands/snapshot.rs b/crates/ov_cli/src/commands/snapshot.rsnew file mode 100644index 000000000..15297032b--- /dev/null+++ b/crates/ov_cli/src/commands/snapshot.rs@@ -0,0 +1,201 @@+use std::io::Write;+use std::path::PathBuf;++use serde_json::{json, Value};++use crate::client::{HttpClient, SnapshotCommitReq, SnapshotRestoreReq, SnapshotShowResult};+use crate::error::Result;+use crate::output::{OutputFormat, output_success};+use crate::SnapshotCmd;++pub async fn dispatch(+ client: &HttpClient,+ cmd: SnapshotCmd,+ output_format: OutputFormat,+ compact: bool,+) -> Result<()> {+ match cmd {+ SnapshotCmd::Commit {+ message,+ paths,+ branch,+ author_name,+ author_email,+ } => {+ let req = SnapshotCommitReq {+ message,+ paths,+ branch,+ author_name,+ author_email,+ };+ let value = client.snapshot_commit(&req).await?;+ print_commit(&value, output_format, compact);+ Ok(())+ }+ SnapshotCmd::Restore {+ project_dir,+ source_commit,+ branch,+ dry_run,+ message,+ author_name,+ author_email,+ } => {+ let req = SnapshotRestoreReq {+ project_dir,+ source_commit,+ branch,+ dry_run,+ message,+ author_name,+ author_email,+ };+ let value = client.snapshot_restore(&req).await?;+ print_restore(&value, output_format, compact);+ Ok(())+ }+ SnapshotCmd::Show {+ target_ref,+ path,+ out_path,+ } => {+ let result = client.snapshot_show(&target_ref, path.as_deref()).await?;+ handle_show(result, out_path, output_format, compact)+ }+ SnapshotCmd::Log { branch, limit } => {+ let value = client.snapshot_log(&branch, limit).await?;+ print_log(&value, output_format, compact);+ Ok(())+ }+ }+}++fn print_commit(value: &Value, output_format: OutputFormat, compact: bool) {+ if matches!(output_format, OutputFormat::Json) {+ output_success(value, output_format, compact);+ return;+ }+ // The server returns the inner result dict (BaseClient unwraps the envelope).+ // It is already a flat object, so hand it to the shared table renderer.+ output_success(value, OutputFormat::Table, compact);+}++fn print_restore(value: &Value, output_format: OutputFormat, compact: bool) {+ if matches!(output_format, OutputFormat::Json) {+ output_success(value, output_format, compact);+ return;+ }+ // Dry-run shape nests counts under {diff: {to_write, to_delete, unchanged}},+ // which the generic renderer cannot flatten. Reshape it into a flat dict;+ // the applied/noop shapes are already flat and render directly.+ let display = if let Some(diff) = value.get("diff") {+ let count = |key: &str| {+ diff.get(key)+ .and_then(|v| v.as_array())+ .map(|a| a.len())+ .unwrap_or(0)+ };+ json!({+ "result": "dry-run",+ "to_write": count("to_write"),+ "to_delete": count("to_delete"),+ "unchanged": count("unchanged"),+ })+ } else {+ value.clone()+ };+ output_success(&display, OutputFormat::Table, compact);+}++fn handle_show(+ result: SnapshotShowResult,+ out_path: Option<PathBuf>,+ output_format: OutputFormat,+ compact: bool,+) -> Result<()> {+ match result {+ SnapshotShowResult::Metadata(meta) => {+ if matches!(output_format, OutputFormat::Json) {+ output_success(&meta, output_format, compact);+ return Ok(());+ }+ // Flatten the `parents` array into a scalar so the whole object+ // renders as a single key/value table instead of the renderer+ // collapsing onto just the list field.+ let mut display = serde_json::Map::new();+ for key in ["oid", "tree", "author", "committer"] {+ if let Some(v) = meta.get(key) {+ display.insert(key.to_string(), v.clone());+ }+ }+ if let Some(parents) = meta.get("parents").and_then(|v| v.as_array()) {+ let names: Vec<String> = parents+ .iter()+ .filter_map(|v| v.as_str().map(String::from))+ .collect();+ display.insert("parents".to_string(), Value::String(names.join(", ")));+ }+ if let Some(msg) = meta.get("message").and_then(|v| v.as_str()) {+ display.insert("message".to_string(), Value::String(msg.to_string()));+ }+ output_success(&Value::Object(display), OutputFormat::Table, compact);+ Ok(())+ }+ SnapshotShowResult::Blob { oid, bytes, size } => {+ if matches!(output_format, OutputFormat::Json) {+ let envelope = serde_json::json!({"oid": oid, "size": size});+ output_success(&envelope, output_format, compact);+ if let Some(path) = out_path {+ let mut f = std::fs::File::create(&path)?;+ f.write_all(&bytes)?;+ }+ return Ok(());+ }+ match out_path {+ Some(path) => {+ let mut f = std::fs::File::create(&path)?;+ f.write_all(&bytes)?;+ eprintln!("Wrote {} bytes from {} to {}", size, &oid[..12.min(oid.len())], path.display());+ }+ None => {+ let mut out = std::io::stdout().lock();+ out.write_all(&bytes)?;+ eprintln!("Read {} bytes from {}", size, &oid[..12.min(oid.len())]);+ }+ }+ Ok(())+ }+ }+}++fn print_log(value: &Value, output_format: OutputFormat, compact: bool) {+ if matches!(output_format, OutputFormat::Json) {+ output_success(value, output_format, compact);+ return;+ }+ // value is the unwrapped "result" — a JSON array of commit entries with+ // nested authors and multi-line messages. Flatten each entry into a row so+ // the shared renderer produces an aligned table like the other commands.+ let entries = value.as_array().cloned().unwrap_or_default();+ let rows: Vec<Value> = entries+ .iter()+ .map(|entry| {+ let oid = entry.get("oid").and_then(|v| v.as_str()).unwrap_or("");+ let short = oid.get(..12).unwrap_or(oid);+ let msg_full = entry.get("message").and_then(|v| v.as_str()).unwrap_or("");+ let subject = msg_full.lines().next().unwrap_or("");+ let author = entry+ .get("author")+ .and_then(|a| a.get("name").or_else(|| a.as_str().map(|_| a)))+ .and_then(|v| v.as_str())+ .unwrap_or("");+ json!({+ "oid": short,+ "author": author,+ "subject": subject,+ })+ })+ .collect();+ output_success(&rows, OutputFormat::Table, compact);+}diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rsindex 96a5fc955..48eb8666d 100644--- a/crates/ov_cli/src/help_ui.rs+++ b/crates/ov_cli/src/help_ui.rs@@ -81,7 +81,7 @@ const CONFIG_STATUS: &[HelpCommand] = help_commands![];const IMPORT_EXPORT_SESSIONS: &[HelpCommand] = help_commands![- "import", "export", "backup", "restore", "session", "privacy"+ "import", "export", "backup", "restore", "snapshot", "session", "privacy"];const INTERACTIVE_ADMIN: &[HelpCommand] = help_commands![@@ -473,6 +473,106 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Show exact arguments for a session operation.",}],},+ CommandHelpSpec {+ path: &["snapshot"],+ purpose: "Manage workspace snapshots: commit, restore, show, and walk history.",+ examples: &[+ HelpItem {+ label: "ov snapshot commit -m \"checkpoint before refactor\"",+ description: "Commit the current workspace state.",+ },+ HelpItem {+ label: "ov snapshot log --branch main",+ description: "Walk commit history, newest first.",+ },+ HelpItem {+ label: "ov snapshot restore viking://projects/acme <commit> --dry-run",+ description: "Preview restoring a directory to a past snapshot.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot <subcommand> --help",+ description: "Show exact arguments for a snapshot operation.",+ }],+ },+ CommandHelpSpec {+ path: &["snapshot", "commit"],+ purpose: "Commit the current workspace state as a new snapshot.",+ examples: &[+ HelpItem {+ label: "ov snapshot commit -m \"checkpoint before refactor\"",+ description: "Commit the full workspace on the main branch.",+ },+ HelpItem {+ label: "ov snapshot commit -m \"docs only\" --paths viking://docs",+ description: "Commit only the given viking:// URIs. Directories are expanded recursively (with snapshot pruning rules applied).",+ },+ ],+ next_steps: &[+ HelpItem {+ label: "ov snapshot log --branch main",+ description: "Confirm the new commit in history.",+ },+ HelpItem {+ label: "ov snapshot show <commit>",+ description: "Inspect the commit metadata.",+ },+ ],+ },+ CommandHelpSpec {+ path: &["snapshot", "restore"],+ purpose: "Restore a project directory to a past snapshot via a forward commit.",+ examples: &[+ HelpItem {+ label: "ov snapshot restore viking://projects/acme <commit> --dry-run",+ description: "Preview which files would change.",+ },+ HelpItem {+ label: "ov snapshot restore viking://projects/acme <commit> -m \"rollback\"",+ description: "Apply the restore as a new commit.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot log --branch main",+ description: "Verify the restore commit landed.",+ }],+ },+ CommandHelpSpec {+ path: &["snapshot", "show"],+ purpose: "Show a commit's metadata, or a single blob at a path.",+ examples: &[+ HelpItem {+ label: "ov snapshot show <commit>",+ description: "Print commit metadata.",+ },+ HelpItem {+ label: "ov snapshot show <commit> --path viking://docs/spec.md --out-file spec.md",+ description: "Write a file blob from the snapshot to disk.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot log --branch main",+ description: "Find another commit to inspect.",+ }],+ },+ CommandHelpSpec {+ path: &["snapshot", "log"],+ purpose: "Walk commit history for a branch, newest first.",+ examples: &[+ HelpItem {+ label: "ov snapshot log --branch main",+ description: "Show the latest commits on main.",+ },+ HelpItem {+ label: "ov snapshot log --branch main --limit 50",+ description: "Show more history entries.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot show <commit>",+ description: "Inspect a commit from the log.",+ }],+ },CommandHelpSpec {path: &["add-memory"],purpose: "Add a memory directly from text or JSON messages.",@@ -1651,6 +1751,11 @@ fn localized_command_purpose(spec: &CommandHelpSpec, language: Language) -> &str["health"] => "快速检查服务器是否可连接。",["status"] => "查看 OpenViking 服务器诊断状态。",["language"] => "选择 OpenViking CLI 显示语言。",+ ["snapshot"] => "管理工作区快照:提交、恢复、查看,以及遍历历史。",+ ["snapshot", "commit"] => "将当前工作区状态提交为新的快照。",+ ["snapshot", "restore"] => "通过一次前向提交,将项目目录恢复到历史快照。",+ ["snapshot", "show"] => "查看某次提交的元数据,或指定路径下的单个文件内容。",+ ["snapshot", "log"] => "按分支遍历提交历史,最新的在前。",_ => spec.purpose,}}@@ -2113,6 +2218,7 @@ fn localized_command_description<'a>("export" => "导出为 .ovpack","backup" => "创建仅恢复备份","restore" => "恢复备份",+ "snapshot" => "管理工作区快照","tui" => "打开交互式浏览器","chat" => "与 VikingBot 对话","admin" => "管理账户、用户和 API Key",@@ -2329,7 +2435,7 @@ fn version() -> String {fn is_bare_group_help_command(command: &str) -> bool {matches!(command,- "task" | "skills" | "session" | "privacy" | "admin" | "system" | "observer"+ "task" | "skills" | "session" | "snapshot" | "privacy" | "admin" | "system" | "observer")}diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 0a453c384..164857cc6 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -899,6 +899,11 @@ enum Commands {#[command(subcommand)]action: TaskCommands,},+ /// [Version] Manage workspace snapshots (commit, restore, show, log)+ Snapshot {+ #[command(subcommand)]+ cmd: SnapshotCmd,+ },/// [Status] All OpenViking Server components statusStatus {/// Show full component tables@@ -1018,6 +1023,58 @@ enum TaskCommands {},}+#[derive(Subcommand)]+pub(crate) enum SnapshotCmd {+ /// Create a snapshot of current workspace state+ Commit {+ #[arg(short = 'm', long)]+ message: String,+ /// Limit to specific viking:// URIs (comma-separated); accepts files and directories. Directories are expanded recursively with the snapshot pruning rules. Omit to snapshot the full account tree.+ #[arg(long, value_delimiter = ',')]+ paths: Option<Vec<String>>,+ #[arg(long, default_value = "main")]+ branch: String,+ #[arg(long)]+ author_name: Option<String>,+ #[arg(long)]+ author_email: Option<String>,+ },+ /// Restore a project directory or the full account tree to a past snapshot (forward commit)+ Restore {+ /// Commit oid, branch, or tag+ source_commit: String,+ /// Optional viking:// directory or relative tree path; omit for full-tree restore+ project_dir: Option<String>,+ #[arg(long, default_value = "main")]+ branch: String,+ #[arg(long)]+ dry_run: bool,+ #[arg(short = 'm', long)]+ message: Option<String>,+ #[arg(long)]+ author_name: Option<String>,+ #[arg(long)]+ author_email: Option<String>,+ },+ /// Show a commit's metadata, or a single blob at a path+ Show {+ target_ref: String,+ /// viking:// URI of a file; omit to show commit metadata+ #[arg(long)]+ path: Option<String>,+ /// Write blob bytes to this file (default: stdout)+ #[arg(long = "out-file")]+ out_path: Option<std::path::PathBuf>,+ },+ /// Walk commit history (newest first)+ Log {+ #[arg(long, default_value = "main")]+ branch: String,+ #[arg(long, default_value_t = 20)]+ limit: u32,+ },+}+#[derive(Subcommand)]enum SystemCommands {/// Wait for queued async processing to complete@@ -2769,6 +2826,10 @@ async fn main() {}}},+ Commands::Snapshot { cmd } => {+ let client = ctx.get_client();+ commands::snapshot::dispatch(&client, cmd, ctx.output_format, ctx.compact).await+ }Commands::Status { verbose } => {let client = ctx.get_client();commands::system::diagnostic_status(diff --git a/crates/ragfs-python/Cargo.toml b/crates/ragfs-python/Cargo.tomlindex acfe14d23..65b0c801a 100644--- a/crates/ragfs-python/Cargo.toml+++ b/crates/ragfs-python/Cargo.toml@@ -8,7 +8,9 @@ publish = false[lib]name = "ragfs_python"-crate-type = ["cdylib"]+# rlib is needed so `cargo test` can build a test binary that links against+# this crate's symbols. cdylib is what maturin packages as the Python .so.+crate-type = ["cdylib", "rlib"][features]default = ["extension-module", "s3", "cache-redis"]@@ -22,6 +24,10 @@ ragfs-cache-redis = { path = "../ragfs-cache-redis", optional = true }pyo3 = { version = "0.27", features = ["abi3", "abi3-py310"] }tokio = { version = "1", features = ["full"] }serde_json = "1.0"+serde = { version = "1", features = ["derive"] }+toml = "0.8"+gix-hash = "0.14"+bytes = "1.5"[lints.rust]unexpected_cfgs = { level = "warn", check-cfg = ['cfg(feature, values("yuanrong-native", "mooncake-native"))'] }diff --git a/crates/ragfs-python/src/git.rs b/crates/ragfs-python/src/git.rsnew file mode 100644index 000000000..5c1ae32bd--- /dev/null+++ b/crates/ragfs-python/src/git.rs@@ -0,0 +1,872 @@+//! PyO3 binding helpers for the Git version-control service.+//!+//! This module owns:+//! - Backend construction (`build_git_service`) from a `GitConfig`+//! - Request parsers: `parse_commit_request`, `parse_restore_request`, `parse_show_request`+//! (added in later tasks)+//! - Response converters: `commit_response_to_pydict`, `restore_response_to_pydict`,+//! `show_response_to_pydict` (added in later tasks)+//! - Error mapping `map_git_error` (added in later tasks)+//!+//! The free functions are invoked from thin `#[pymethods]` wrappers in `lib.rs`.++use std::sync::Arc;++use pyo3::exceptions::{PyRuntimeError, PyValueError};+use pyo3::prelude::*;++use ragfs::core::FileSystem;+use ragfs::git::{+ GitConfig, GitService, IndexStore, LocalIndexStore, LocalObjectStore, LocalRefStore,+ ObjectStore, RefStore,+};++#[cfg(feature = "s3")]+use ragfs::git::{CasMode, S3Config, S3IndexStore, S3ObjectStore, S3RefStore};++/// Build a `GitService` from a `GitConfig` and the binding's MountableFS.+///+/// Returns `Ok(None)` when `enabled = false`; `Err(PyErr)` if the config is+/// invalid (missing required section, unknown backend, etc.).+///+/// Backend-specific notes:+/// - `local`: requires `[git.local]` with `base_dir`. Builds `LocalObjectStore`+/// and `LocalRefStore`, both rooted at `base_dir`.+/// - `s3` (feature-gated): requires `[git.s3]` with `bucket`, `region`.+/// `access_key` and `secret_key` are read directly from the config; when+/// omitted, the AWS SDK default credentials chain is used.+pub fn build_git_service(+ cfg: &GitConfig,+ vfs: Arc<dyn FileSystem>,+) -> PyResult<Option<Arc<GitService>>> {+ if !cfg.enabled {+ return Ok(None);+ }++ let (object_store, ref_store, index_store): (+ Arc<dyn ObjectStore>,+ Arc<dyn RefStore>,+ Option<Arc<dyn IndexStore>>,+ ) = match cfg.backend.as_str() {+ "local" => {+ let lc = cfg+ .local+ .as_ref()+ .ok_or_else(|| PyValueError::new_err("[git.local] missing"))?;+ let os = Arc::new(LocalObjectStore::new(lc.base_dir.clone()));+ let rs = Arc::new(LocalRefStore::new(lc.base_dir.clone()));+ let is: Option<Arc<dyn IndexStore>> = if cfg.tuning.commit_index_enabled {+ Some(Arc::new(LocalIndexStore::new(lc.base_dir.clone())))+ } else {+ None+ };+ (os, rs, is)+ }+ #[cfg(feature = "s3")]+ "s3" => build_s3_service(cfg)?,+ #[cfg(not(feature = "s3"))]+ "s3" => {+ return Err(PyRuntimeError::new_err(+ "git backend 's3' requested but ragfs-python built without `s3` feature",+ ));+ }+ other => {+ return Err(PyValueError::new_err(format!(+ "unsupported git backend: {}",+ other+ )));+ }+ };++ Ok(Some(Arc::new(+ GitService::with_index(vfs, object_store, ref_store, index_store)+ .with_blob_exists_precheck(cfg.tuning.blob_exists_precheck_enabled),+ )))+}++#[cfg(feature = "s3")]+fn build_s3_service(+ cfg: &GitConfig,+) -> PyResult<(+ Arc<dyn ObjectStore>,+ Arc<dyn RefStore>,+ Option<Arc<dyn IndexStore>>,+)> {+ let sc = cfg+ .s3+ .as_ref()+ .ok_or_else(|| PyValueError::new_err("[git.s3] missing"))?;++ let access_key_id = match sc.access_key.as_deref() {+ Some(v) if !v.is_empty() => Some(v.to_string()),+ _ => None,+ };+ let secret_access_key = match sc.secret_key.as_deref() {+ Some(v) if !v.is_empty() => Some(v.to_string()),+ _ => None,+ };++ let cas_mode = match sc.cas_mode.as_str() {+ "native" => CasMode::Native,+ "redis_lock" => CasMode::RedisLock,+ other => {+ return Err(PyValueError::new_err(format!(+ "unsupported cas_mode: {}",+ other+ )));+ }+ };++ let s3_config = S3Config {+ bucket: sc.bucket.clone(),+ prefix: sc.prefix.clone(),+ region: sc.region.clone(),+ endpoint: if sc.endpoint.is_empty() {+ None+ } else {+ Some(sc.endpoint.clone())+ },+ access_key_id,+ secret_access_key,+ use_path_style: sc.use_path_style,+ cas_mode,+ };++ let rt = tokio::runtime::Handle::try_current()+ .map_err(|_| PyRuntimeError::new_err("build_s3_service must run inside a tokio runtime"))?;+ let os_cfg = s3_config.clone();+ let object_store = Arc::new(+ rt.block_on(async move { S3ObjectStore::from_config(os_cfg).await })+ .map_err(|e| PyRuntimeError::new_err(format!("S3ObjectStore: {}", e)))?,+ ) as Arc<dyn ObjectStore>;++ let rs_cfg = s3_config.clone();+ let ref_store = Arc::new(+ rt.block_on(async move { S3RefStore::from_config(rs_cfg).await })+ .map_err(|e| PyRuntimeError::new_err(format!("S3RefStore: {}", e)))?,+ ) as Arc<dyn RefStore>;++ let index_store: Option<Arc<dyn IndexStore>> = if cfg.tuning.commit_index_enabled {+ let is_cfg = s3_config;+ Some(Arc::new(+ rt.block_on(async move { S3IndexStore::from_config(is_cfg).await })+ .map_err(|e| PyRuntimeError::new_err(format!("S3IndexStore: {}", e)))?,+ ) as Arc<dyn IndexStore>)+ } else {+ None+ };++ Ok((object_store, ref_store, index_store))+}++/// Map a `GitError` to the appropriate Python exception.+///+/// Loads exception classes from the `openviking.pyagfs` module. When the+/// module is not importable (e.g. during unit tests), falls back to+/// `PyRuntimeError` with the same message.+pub fn map_git_error(py: Python<'_>, e: ragfs::git::GitError) -> PyErr {+ use ragfs::git::{GitError, ObjectStoreError, RefStoreError};+ let msg = e.to_string();+ match e {+ GitError::FeatureDisabled => new_py_err_pub(py, "AGFSNotSupportedError", msg),+ GitError::ConcurrentCommit { .. } => new_py_err_pub(py, "GitConcurrentCommitError", msg),+ GitError::PathNotFound(_) => new_py_err_pub(py, "AGFSNotFoundError", msg),+ GitError::PathIsDirectory(_) => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::SubtreeNotFoundInCommit { .. } => new_py_err_pub(py, "AGFSNotFoundError", msg),+ GitError::InvalidAccountId(_) => new_py_err_pub(py, "AGFSInvalidPathError", msg),+ GitError::InvalidProjectDir(_) => new_py_err_pub(py, "AGFSInvalidPathError", msg),+ GitError::InvalidPath(_) => new_py_err_pub(py, "AGFSInvalidPathError", msg),+ GitError::BlobTooLarge { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::TooManyFiles { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::CorruptedObject(_) => new_py_err_pub(py, "AGFSInternalError", msg),+ GitError::RefStore(RefStoreError::NotFound(_)) => {+ new_py_err_pub(py, "AGFSNotFoundError", msg)+ }+ GitError::RefStore(RefStoreError::Conflict { .. }) => {+ new_py_err_pub(py, "GitConcurrentCommitError", msg)+ }+ GitError::OidPrefixNotFound { .. } => new_py_err_pub(py, "AGFSNotFoundError", msg),+ GitError::AmbiguousOid { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::ObjectStore(ObjectStoreError::NotFound(_)) => {+ new_py_err_pub(py, "AGFSNotFoundError", msg)+ }+ GitError::RestoreWritebackPartial(p) => writeback_partial_to_pyerr(py, *p, msg),+ GitError::ObjectStore(_)+ | GitError::RefStore(_)+ | GitError::Vfs(_)+ | GitError::Other(_) => PyRuntimeError::new_err(msg),+ }+}++/// Build a Python exception carrying the structured `RestoreWritebackPartial`+/// payload. Falls back to `PyRuntimeError` when `openviking.pyagfs` is not+/// importable (e.g. cargo-test environment) — in that case the structured+/// data is lost, but the error message still survives.+fn writeback_partial_to_pyerr(py: Python<'_>, p: RestoreWritebackPartial, msg: String) -> PyErr {+ let exc_class = match PyModule::import(py, "openviking.pyagfs")+ .and_then(|m| m.getattr("GitRestoreWritebackPartialError"))+ {+ Ok(c) => c,+ Err(_) => {+ return PyRuntimeError::new_err(format!(+ "{msg} (structured payload dropped: pyagfs unavailable)"+ ));+ }+ };++ let payload = PyDict::new(py);+ // Strings + ints marshal trivially; (String, String) tuples become+ // Python tuples via pyo3's IntoPy impl.+ let set_oid =+ |k: &str, oid: &gix_hash::ObjectId| -> PyResult<()> { payload.set_item(k, oid_hex(oid)) };++ let build = || -> PyResult<()> {+ set_oid("new_commit_oid", &p.new_commit_oid)?;+ set_oid("source_commit", &p.source_commit)?;+ set_oid("parent_commit", &p.parent_commit)?;+ payload.set_item("written", p.written)?;+ payload.set_item("deleted", p.deleted)?;+ payload.set_item("unchanged", p.unchanged)?;+ payload.set_item("written_paths", p.written_paths.clone())?;+ payload.set_item("deleted_paths", p.deleted_paths.clone())?;+ payload.set_item("failed_writes", p.failed_writes.clone())?;+ payload.set_item("failed_deletes", p.failed_deletes.clone())?;+ Ok(())+ };+ if let Err(e) = build() {+ return e;+ }++ match exc_class.call1((msg.clone(), &payload)) {+ Ok(instance) => PyErr::from_value(instance),+ Err(_) => PyRuntimeError::new_err(format!(+ "{msg} (structured payload dropped: failed to instantiate \+ GitRestoreWritebackPartialError)"+ )),+ }+}++/// Local copy of the new_py_err pattern used in lib.rs. We duplicate it here+/// to keep git.rs self-contained — lib.rs's helper is private. If lib.rs's+/// helper is later made `pub(crate)`, this can be deleted in favor of that.+pub fn new_py_err_pub(py: Python<'_>, name: &str, msg: String) -> PyErr {+ let exc = PyModule::import(py, "openviking.pyagfs")+ .and_then(|m| m.getattr(name))+ .and_then(|exc| Ok(exc.cast_into::<pyo3::types::PyType>()?));+ match exc {+ Ok(exc) => PyErr::from_type(exc, msg),+ Err(_) => PyRuntimeError::new_err(msg),+ }+}++use pyo3::types::{PyBytes, PyDict, PyList};+use ragfs::git::{+ Actor, CommitRequest, CommitResponse, RestoreDiff, RestoreRequest, RestoreResponse,+ RestoreWritebackPartial, ShowRequest, ShowResponse,+};++// ---------- request parsers ----------++fn require_str(kwargs: &Bound<PyDict>, key: &str) -> PyResult<String> {+ let val = kwargs+ .get_item(key)?+ .ok_or_else(|| PyValueError::new_err(format!("missing required kwarg: {}", key)))?;+ val.extract::<String>()+ .map_err(|_| PyValueError::new_err(format!("kwarg {} must be a string", key)))+}++fn optional_str(kwargs: &Bound<PyDict>, key: &str) -> PyResult<Option<String>> {+ match kwargs.get_item(key)? {+ Some(v) if !v.is_none() => v+ .extract::<String>()+ .map(Some)+ .map_err(|_| PyValueError::new_err(format!("kwarg {} must be a string", key))),+ _ => Ok(None),+ }+}++fn optional_bool(kwargs: &Bound<PyDict>, key: &str, default: bool) -> PyResult<bool> {+ match kwargs.get_item(key)? {+ Some(v) if !v.is_none() => v+ .extract::<bool>()+ .map_err(|_| PyValueError::new_err(format!("kwarg {} must be a bool", key))),+ _ => Ok(default),+ }+}++fn optional_string_list(kwargs: &Bound<PyDict>, key: &str) -> PyResult<Option<Vec<String>>> {+ match kwargs.get_item(key)? {+ Some(v) if !v.is_none() => v+ .extract::<Vec<String>>()+ .map(Some)+ .map_err(|_| PyValueError::new_err(format!("kwarg {} must be a list of strings", key))),+ _ => Ok(None),+ }+}++pub fn parse_commit_request(kwargs: &Bound<PyDict>) -> PyResult<CommitRequest> {+ Ok(CommitRequest {+ account: require_str(kwargs, "account")?,+ branch: require_str(kwargs, "branch")?,+ message: require_str(kwargs, "message")?,+ paths: optional_string_list(kwargs, "paths")?,+ author_name: require_str(kwargs, "author_name")?,+ author_email: require_str(kwargs, "author_email")?,+ })+}++pub fn parse_restore_request(kwargs: &Bound<PyDict>) -> PyResult<RestoreRequest> {+ Ok(RestoreRequest {+ account: require_str(kwargs, "account")?,+ branch: require_str(kwargs, "branch")?,+ project_dir: optional_str(kwargs, "project_dir")?,+ source_commit: require_str(kwargs, "source_commit")?,+ dry_run: optional_bool(kwargs, "dry_run", false)?,+ message: optional_str(kwargs, "message")?,+ author_name: require_str(kwargs, "author_name")?,+ author_email: require_str(kwargs, "author_email")?,+ })+}++pub fn parse_show_request(kwargs: &Bound<PyDict>) -> PyResult<ShowRequest> {+ Ok(ShowRequest {+ account: require_str(kwargs, "account")?,+ target_ref: require_str(kwargs, "target_ref")?,+ path: optional_str(kwargs, "path")?,+ })+}++// ---------- response converters ----------++fn oid_hex(oid: &gix_hash::ObjectId) -> String {+ oid.to_hex().to_string()+}++fn actor_to_dict(py: Python<'_>, a: &Actor) -> PyResult<Py<PyDict>> {+ let d = PyDict::new(py);+ d.set_item("name", &a.name)?;+ d.set_item("email", &a.email)?;+ d.set_item("time_seconds", a.time_seconds)?;+ d.set_item("tz_offset_seconds", a.tz_offset_seconds)?;+ Ok(d.into())+}++pub fn commit_response_to_pydict(py: Python<'_>, resp: CommitResponse) -> PyResult<Py<PyAny>> {+ let d = PyDict::new(py);+ match resp {+ CommitResponse::Created {+ commit_oid,+ changed,+ } => {+ d.set_item("result", "created")?;+ d.set_item("commit_oid", oid_hex(&commit_oid))?;+ d.set_item("changed", changed)?;+ }+ CommitResponse::Noop { commit_oid } => {+ d.set_item("result", "noop")?;+ d.set_item("commit_oid", oid_hex(&commit_oid))?;+ }+ }+ Ok(d.into_any().unbind())+}++fn diff_to_dict(py: Python<'_>, diff: &RestoreDiff) -> PyResult<Py<PyDict>> {+ let d = PyDict::new(py);+ let to_write = PyList::empty(py);+ for (path, oid) in &diff.to_write {+ let pair = PyDict::new(py);+ pair.set_item("path", path)?;+ pair.set_item("oid", oid_hex(oid))?;+ to_write.append(pair)?;+ }+ d.set_item("to_write", to_write)?;+ d.set_item("to_delete", diff.to_delete.clone())?;+ d.set_item("unchanged", diff.unchanged.clone())?;+ Ok(d.into())+}++pub fn restore_response_to_pydict(py: Python<'_>, resp: RestoreResponse) -> PyResult<Py<PyAny>> {+ let d = PyDict::new(py);+ match resp {+ RestoreResponse::Applied {+ new_commit_oid,+ source_commit,+ parent_commit,+ written,+ deleted,+ unchanged,+ written_paths,+ deleted_paths,+ } => {+ d.set_item("result", "applied")?;+ d.set_item("new_commit_oid", oid_hex(&new_commit_oid))?;+ d.set_item("source_commit", oid_hex(&source_commit))?;+ d.set_item("parent_commit", oid_hex(&parent_commit))?;+ d.set_item("written", written)?;+ d.set_item("deleted", deleted)?;+ d.set_item("unchanged", unchanged)?;+ d.set_item("written_paths", written_paths)?;+ d.set_item("deleted_paths", deleted_paths)?;+ }+ RestoreResponse::Noop { head, source } => {+ d.set_item("result", "noop")?;+ d.set_item("head", oid_hex(&head))?;+ d.set_item("source", oid_hex(&source))?;+ }+ RestoreResponse::DryRun { diff, head, source } => {+ d.set_item("result", "dry_run")?;+ d.set_item("head", oid_hex(&head))?;+ d.set_item("source", oid_hex(&source))?;+ d.set_item("diff", diff_to_dict(py, &diff)?)?;+ }+ }+ Ok(d.into_any().unbind())+}++pub fn show_response_to_pydict(py: Python<'_>, resp: ShowResponse) -> PyResult<Py<PyAny>> {+ let d = PyDict::new(py);+ match resp {+ ShowResponse::Commit {+ oid,+ tree,+ parents,+ author,+ committer,+ message,+ } => {+ d.set_item("oid", oid_hex(&oid))?;+ d.set_item("tree", oid_hex(&tree))?;+ let plist = PyList::empty(py);+ for p in &parents {+ plist.append(oid_hex(p))?;+ }+ d.set_item("parents", plist)?;+ d.set_item("author", actor_to_dict(py, &author)?)?;+ d.set_item("committer", actor_to_dict(py, &committer)?)?;+ d.set_item("message", message)?;+ }+ ShowResponse::Blob { oid, size, bytes } => {+ d.set_item("oid", oid_hex(&oid))?;+ d.set_item("size", size)?;+ d.set_item("bytes", PyBytes::new(py, &bytes))?;+ }+ }+ Ok(d.into_any().unbind())+}++#[cfg(test)]+mod tests {+ use super::*;+ use ragfs::core::MountableFS;+ use ragfs::git::GitError;+ use std::sync::Arc;++ fn local_cfg(base_dir: &str) -> ragfs::git::GitConfig {+ ragfs::git::GitConfig {+ enabled: true,+ backend: "local".into(),+ default_branch: "main".into(),+ author_name: "test".into(),+ author_email: "t@e".into(),+ local: Some(ragfs::git::GitLocalConfig {+ base_dir: base_dir.into(),+ }),+ s3: None,+ tuning: Default::default(),+ }+ }++ #[tokio::test]+ async fn build_git_service_disabled_returns_none() {+ let fs = Arc::new(MountableFS::new()) as Arc<dyn ragfs::core::FileSystem>;+ let mut cfg = local_cfg("/tmp/ov-git-test-disabled");+ cfg.enabled = false;+ let svc = build_git_service(&cfg, fs).expect("build ok");+ assert!(svc.is_none());+ }++ #[tokio::test]+ async fn build_git_service_local_returns_some() {+ let fs = Arc::new(MountableFS::new()) as Arc<dyn ragfs::core::FileSystem>;+ let cfg = local_cfg("/tmp/ov-git-test-local");+ let svc = build_git_service(&cfg, fs).expect("build ok");+ assert!(svc.is_some());+ }++ #[tokio::test]+ async fn build_git_service_unknown_backend_errors() {+ // Building a PyErr requires the Python interpreter to be initialized;+ // the `extension-module` feature disables auto-initialize.+ Python::initialize();+ let fs = Arc::new(MountableFS::new()) as Arc<dyn ragfs::core::FileSystem>;+ let mut cfg = local_cfg("/tmp/ov-git-test-bad");+ cfg.backend = "bogus".into();+ // `GitService` is not `Debug`, so we can't use `unwrap_err()`; match instead.+ let err = match build_git_service(&cfg, fs) {+ Ok(_) => panic!("expected error for bogus backend"),+ Err(e) => e,+ };+ assert!(err.to_string().contains("unsupported git backend"));+ }++ #[tokio::test]+ async fn build_git_service_local_without_section_errors() {+ Python::initialize();+ let fs = Arc::new(MountableFS::new()) as Arc<dyn ragfs::core::FileSystem>;+ let mut cfg = local_cfg("/tmp/ov-git-test-nolocal");+ cfg.local = None;+ let err = match build_git_service(&cfg, fs) {+ Ok(_) => panic!("expected error when [git.local] missing"),+ Err(e) => e,+ };+ assert!(err.to_string().contains("[git.local] missing"));+ }++ #[test]+ fn map_git_error_feature_disabled() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let err = map_git_error(py, GitError::FeatureDisabled);+ // We don't require the openviking.pyagfs module to be importable+ // in this Rust-only test, so the fallback PyRuntimeError is fine.+ // We just assert that mapping does not panic and yields a PyErr.+ assert!(err.to_string().to_lowercase().contains("git"));+ });+ }++ #[test]+ fn map_git_error_concurrent_commit() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let err = map_git_error(+ py,+ GitError::ConcurrentCommit {+ ref_name: "refs/heads/main".into(),+ expected: None,+ actual: None,+ },+ );+ assert!(err.to_string().to_lowercase().contains("concurrent"));+ });+ }++ /// `RestoreWritebackPartial` must round-trip through `map_git_error`+ /// without panicking. When `openviking.pyagfs` is not importable (the+ /// usual case in pure cargo-test environments) the helper falls back to+ /// `PyRuntimeError` and tags the message so the operator notices the+ /// dropped payload; we only assert on the message preamble here.+ #[test]+ fn map_git_error_writeback_partial() {+ use ragfs::git::RestoreWritebackPartial;+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let payload = RestoreWritebackPartial {+ new_commit_oid: gix_hash::ObjectId::null(gix_hash::Kind::Sha1),+ source_commit: gix_hash::ObjectId::null(gix_hash::Kind::Sha1),+ parent_commit: gix_hash::ObjectId::null(gix_hash::Kind::Sha1),+ written: 1,+ deleted: 0,+ unchanged: 0,+ written_paths: vec!["resources/proj_a/b.md".to_string()],+ deleted_paths: vec![],+ failed_writes: vec![(+ "resources/proj_a/a.md".to_string(),+ "forced write failure".to_string(),+ )],+ failed_deletes: vec![],+ };+ let err = map_git_error(py, GitError::RestoreWritebackPartial(Box::new(payload)));+ let s = err.to_string().to_lowercase();+ assert!(+ s.contains("restore writeback partial"),+ "expected partial message, got {s:?}"+ );+ // The Display includes counts derived from the payload.+ assert!(+ s.contains("1 write"),+ "expected write count in message: {s:?}"+ );+ });+ }++ #[test]+ fn map_git_error_path_not_found() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let err = map_git_error(py, GitError::PathNotFound("foo/bar".into()));+ assert!(err.to_string().contains("foo/bar"));+ });+ }++ #[test]+ fn map_git_error_invalid_account() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let err = map_git_error(py, GitError::InvalidAccountId("../bad".into()));+ assert!(err.to_string().contains("bad"));+ });+ }++ #[test]+ fn map_git_error_blob_too_large() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let err = map_git_error(+ py,+ GitError::BlobTooLarge {+ size: 200,+ limit: 100,+ },+ );+ assert!(err.to_string().contains("200"));+ });+ }++ use pyo3::types::PyDict;++ #[test]+ fn parse_commit_request_required_fields() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "acct1").unwrap();+ kwargs.set_item("branch", "main").unwrap();+ kwargs.set_item("message", "hello").unwrap();+ kwargs.set_item("author_name", "alice").unwrap();+ kwargs.set_item("author_email", "[email protected]").unwrap();+ let req = parse_commit_request(&kwargs).expect("parses");+ assert_eq!(req.account, "acct1");+ assert_eq!(req.branch, "main");+ assert_eq!(req.message, "hello");+ assert!(req.paths.is_none());+ assert_eq!(req.author_name, "alice");+ assert_eq!(req.author_email, "[email protected]");+ });+ }++ #[test]+ fn parse_commit_request_with_paths_list() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "a").unwrap();+ kwargs.set_item("branch", "main").unwrap();+ kwargs.set_item("message", "m").unwrap();+ kwargs.set_item("author_name", "n").unwrap();+ kwargs.set_item("author_email", "e").unwrap();+ kwargs+ .set_item("paths", vec!["resources/a.md", "resources/b.md"])+ .unwrap();+ let req = parse_commit_request(&kwargs).expect("parses");+ assert_eq!(req.paths.as_ref().unwrap().len(), 2);+ assert_eq!(req.paths.as_ref().unwrap()[0], "resources/a.md");+ });+ }++ #[test]+ fn parse_commit_request_missing_required_errors() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("branch", "main").unwrap();+ // missing account, message, author_*+ let err = parse_commit_request(&kwargs).unwrap_err();+ assert!(err.to_string().contains("account"));+ });+ }++ #[test]+ fn parse_restore_request_defaults_project_dir_none() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "a").unwrap();+ kwargs.set_item("branch", "main").unwrap();+ kwargs.set_item("source_commit", "deadbeef").unwrap();+ kwargs.set_item("author_name", "n").unwrap();+ kwargs.set_item("author_email", "e").unwrap();+ let req = parse_restore_request(&kwargs).expect("parses");+ assert!(req.project_dir.is_none());+ assert!(!req.dry_run);+ assert!(req.message.is_none());+ });+ }++ #[test]+ fn parse_restore_request_project_dir_some() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "a").unwrap();+ kwargs.set_item("branch", "main").unwrap();+ kwargs.set_item("project_dir", "resources/proj").unwrap();+ kwargs.set_item("source_commit", "deadbeef").unwrap();+ kwargs.set_item("author_name", "n").unwrap();+ kwargs.set_item("author_email", "e").unwrap();+ let req = parse_restore_request(&kwargs).expect("parses");+ assert_eq!(req.project_dir.as_deref(), Some("resources/proj"));+ });+ }++ #[test]+ fn parse_restore_request_dry_run_and_message() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "a").unwrap();+ kwargs.set_item("branch", "main").unwrap();+ kwargs.set_item("project_dir", "x").unwrap();+ kwargs.set_item("source_commit", "abc123").unwrap();+ kwargs.set_item("author_name", "n").unwrap();+ kwargs.set_item("author_email", "e").unwrap();+ kwargs.set_item("dry_run", true).unwrap();+ kwargs.set_item("message", "custom msg").unwrap();+ let req = parse_restore_request(&kwargs).expect("parses");+ assert!(req.dry_run);+ assert_eq!(req.message.as_deref(), Some("custom msg"));+ });+ }++ #[test]+ fn parse_show_request_with_and_without_path() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let kwargs = PyDict::new(py);+ kwargs.set_item("account", "a").unwrap();+ kwargs.set_item("target_ref", "main").unwrap();+ let req = parse_show_request(&kwargs).expect("parses");+ assert!(req.path.is_none());++ let kwargs2 = PyDict::new(py);+ kwargs2.set_item("account", "a").unwrap();+ kwargs2.set_item("target_ref", "main").unwrap();+ kwargs2.set_item("path", "resources/a.md").unwrap();+ let req2 = parse_show_request(&kwargs2).expect("parses");+ assert_eq!(req2.path.as_deref(), Some("resources/a.md"));+ });+ }++ #[test]+ fn commit_response_created_to_dict() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let oid = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);+ let resp = ragfs::git::CommitResponse::Created {+ commit_oid: oid,+ changed: 3,+ };+ let obj = commit_response_to_pydict(py, resp).expect("converts");+ let d: &Bound<PyDict> = obj.bind(py).downcast().unwrap();+ let result: String = d.get_item("result").unwrap().unwrap().extract().unwrap();+ assert_eq!(result, "created");+ let changed: usize = d.get_item("changed").unwrap().unwrap().extract().unwrap();+ assert_eq!(changed, 3);+ });+ }++ #[test]+ fn commit_response_noop_to_dict() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let oid = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);+ let resp = ragfs::git::CommitResponse::Noop { commit_oid: oid };+ let obj = commit_response_to_pydict(py, resp).expect("converts");+ let d: &Bound<PyDict> = obj.bind(py).downcast().unwrap();+ let result: String = d.get_item("result").unwrap().unwrap().extract().unwrap();+ assert_eq!(result, "noop");+ });+ }++ #[test]+ fn show_response_blob_to_dict_carries_bytes() {+ pyo3::prepare_freethreaded_python();+ Python::attach(|py| {+ let oid = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);+ let resp = ragfs::git::ShowResponse::Blob {+ oid,+ size: 5,+ bytes: bytes::Bytes::from_static(b"hello"),+ };+ let obj = show_response_to_pydict(py, resp).expect("converts");+ let d: &Bound<PyDict> = obj.bind(py).downcast().unwrap();+ let b: Vec<u8> = d.get_item("bytes").unwrap().unwrap().extract().unwrap();+ assert_eq!(b, b"hello".to_vec());+ let size: u64 = d.get_item("size").unwrap().unwrap().extract().unwrap();+ assert_eq!(size, 5);+ });+ }++ // ---------- direct binding: account isolation ----------++ /// Build a `GitService` over local backends, mirroring what the binding's+ /// `build_git_service` does for the `local` backend. The `base_dir` does+ /// not need to exist: a malicious account must be rejected at the+ /// `GitService` boundary *before* any path under `base_dir` is built.+ fn local_git_service() -> Arc<GitService> {+ use ragfs::git::{LocalObjectStore, LocalRefStore};+ let base = std::env::temp_dir().join("ov-git-account-validation-test");+ let vfs = Arc::new(MountableFS::new()) as Arc<dyn ragfs::core::FileSystem>;+ let object_store = Arc::new(LocalObjectStore::new(&base)) as Arc<dyn ObjectStore>;+ let ref_store = Arc::new(LocalRefStore::new(&base)) as Arc<dyn RefStore>;+ Arc::new(GitService::new(vfs, object_store, ref_store))+ }++ #[tokio::test]+ async fn binding_commit_rejects_traversal_account() {+ let svc = local_git_service();+ let req = CommitRequest {+ account: "../escape".into(),+ branch: "main".into(),+ message: "m".into(),+ paths: None,+ author_name: "n".into(),+ author_email: "e".into(),+ };+ let err = svc.commit(req).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn binding_commit_rejects_slash_account() {+ let svc = local_git_service();+ let req = CommitRequest {+ account: "a/b".into(),+ branch: "main".into(),+ message: "m".into(),+ paths: None,+ author_name: "n".into(),+ author_email: "e".into(),+ };+ let err = svc.commit(req).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn binding_show_rejects_backslash_account() {+ let svc = local_git_service();+ let req = ShowRequest {+ account: "a\\b".into(),+ target_ref: "main".into(),+ path: None,+ };+ let err = svc.show(req).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn binding_restore_rejects_empty_account() {+ let svc = local_git_service();+ let req = RestoreRequest {+ account: "".into(),+ branch: "main".into(),+ project_dir: Some("resources/x".into()),+ source_commit: "deadbeef".into(),+ dry_run: false,+ message: None,+ author_name: "n".into(),+ author_email: "e".into(),+ };+ let err = svc.restore(req).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }+}diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex b1d4b01e8..88aabf30c 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -496,6 +496,8 @@ fn cache_policy_from_config(config: &RagfsCacheConfig) -> CachePolicy {)}+mod git;+fn py_detach_blocking<T, F>(py: Python<'_>, f: F) -> TwhereT: Send,@@ -805,6 +807,40 @@ fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {Arc::new(FsContextInner::new(account_id))}+#[derive(serde::Deserialize)]+struct BindingConfig {+ #[serde(default)]+ git: Option<ragfs::git::GitConfig>,+}++fn build_git_from_cfg(+ git_cfg: ragfs::git::GitConfig,+ fs: &Arc<MountableFS>,+ rt: &tokio::runtime::Runtime,+) -> PyResult<(Option<Arc<ragfs::git::GitService>>, Option<String>)> {+ let backend = git_cfg.backend.clone();+ let vfs = fs.clone() as Arc<dyn ragfs::core::FileSystem>;+ let _guard = rt.enter();+ let svc = git::build_git_service(&git_cfg, vfs)?;+ Ok((svc, Some(backend)))+}++fn load_git_from_config(+ path: &str,+ fs: &Arc<MountableFS>,+ rt: &tokio::runtime::Runtime,+) -> PyResult<(Option<Arc<ragfs::git::GitService>>, Option<String>)> {+ let body = std::fs::read_to_string(path).map_err(|e| {+ PyRuntimeError::new_err(format!("read config_path {}: {}", path, e))+ })?;+ let cfg: BindingConfig = toml::from_str(&body)+ .map_err(|e| PyRuntimeError::new_err(format!("parse config_path: {}", e)))?;+ match cfg.git {+ Some(git_cfg) => build_git_from_cfg(git_cfg, fs, rt),+ None => Ok((None, None)),+ }+}+/// RAGFS Python Binding Client.////// Embeds the ragfs filesystem engine directly in the Python process.@@ -816,6 +852,8 @@ struct RAGFSBindingClient {/// Data entry point: `Stats(Encryption(Mountable))` when encrypted, else `Stats(Mountable)`.top: Arc<dyn FileSystem>,rt: tokio::runtime::Runtime,+ git_service: Option<Arc<ragfs::git::GitService>>,+ git_backend: Option<String>,}impl RAGFSBindingClient {@@ -846,11 +884,12 @@ impl RAGFSBindingClient {/// `provider_type` (int) and causes the stack to include an `EncryptionWrappedFS` layer./// Runtime `cache` configuration takes precedence over `config_path`.#[new]- #[pyo3(signature = (config_path=None, config=None))]+ #[pyo3(signature = (config_path=None, config=None, git_config_path=None))]fn new(py: Python<'_>,config_path: Option<&str>,config: Option<HashMap<String, Py<PyAny>>>,+ git_config_path: Option<&str>) -> PyResult<Self> {let rt = tokio::runtime::Runtime::new().map_err(|e| PyRuntimeError::new_err(format!("Failed to create runtime: {}", e)))?;@@ -858,6 +897,7 @@ impl RAGFSBindingClient {// Phase A (holding GIL): parse the sectioned config into an owned RagfsConfig.let mut ragfs_cfg = RagfsConfig::default();let mut runtime_cache_config = None;+ let mut inline_git_cfg: Option<ragfs::git::GitConfig> = None;if let Some(cfg) = config {if let Some(enc_obj) = cfg.get("encryption") {let enc: HashMap<String, Py<PyAny>> = enc_obj.extract(py)?;@@ -885,6 +925,12 @@ impl RAGFSBindingClient {PyRuntimeError::new_err(format!("Invalid cache config: {error}"))})?);}+ if let Some(git_obj) = cfg.get("git") {+ let git_value = py_to_json_value(git_obj.bind(py))?;+ let git_cfg: ragfs::git::GitConfig = serde_json::from_value(git_value)+ .map_err(|e| PyRuntimeError::new_err(format!("Invalid git config: {e}")))?;+ inline_git_cfg = Some(git_cfg);+ }}let cache_config = match runtime_cache_config {@@ -926,10 +972,23 @@ impl RAGFSBindingClient {} else {rt.block_on(build_default_stack(ragfs_cfg))};++ // Build the git service from inline config when present; otherwise fall+ // back to loading the [git] section from a config file path.+ let (git_service, git_backend) = match inline_git_cfg {+ Some(git_cfg) => build_git_from_cfg(git_cfg, &stack.mountable, &rt)?,+ None => match git_config_path {+ Some(path) => load_git_from_config(path, &stack.mountable, &rt)?,+ None => (None, None),+ },+ };+Ok(Self {mountable: stack.mountable,top: stack.top,rt,+ git_service,+ git_backend,})}@@ -937,9 +996,70 @@ impl RAGFSBindingClient {fn health(&self) -> PyResult<HashMap<String, String>> {let mut m = HashMap::new();m.insert("status".to_string(), "healthy".to_string());+ m.insert(+ "git_enabled".to_string(),+ if self.git_service.is_some() { "true".into() } else { "false".into() },+ );+ if let Some(b) = &self.git_backend {+ m.insert("git_backend".to_string(), b.clone());+ }Ok(m)}+ /// Commit a snapshot of the account's tree.+ #[pyo3(signature = (**kwargs))]+ fn git_commit(+ &self,+ py: Python<'_>,+ kwargs: Option<&Bound<'_, PyDict>>,+ ) -> PyResult<Py<PyAny>> {+ let svc = self.git_service.clone().ok_or_else(|| {+ git::new_py_err_pub(py, "AGFSNotSupportedError", "git feature disabled".into())+ })?;+ let empty = PyDict::new(py);+ let kw = kwargs.unwrap_or(&empty);+ let req = git::parse_commit_request(kw)?;+ let resp = py_detach_blocking(py, move || self.rt.block_on(svc.commit(req)))+ .map_err(|e| git::map_git_error(py, e))?;+ git::commit_response_to_pydict(py, resp)+ }++ /// Restore a project_dir subtree to the state at source_commit.+ #[pyo3(signature = (**kwargs))]+ fn git_restore(+ &self,+ py: Python<'_>,+ kwargs: Option<&Bound<'_, PyDict>>,+ ) -> PyResult<Py<PyAny>> {+ let svc = self.git_service.clone().ok_or_else(|| {+ git::new_py_err_pub(py, "AGFSNotSupportedError", "git feature disabled".into())+ })?;+ let empty = PyDict::new(py);+ let kw = kwargs.unwrap_or(&empty);+ let req = git::parse_restore_request(kw)?;+ let resp = py_detach_blocking(py, move || self.rt.block_on(svc.restore(req)))+ .map_err(|e| git::map_git_error(py, e))?;+ git::restore_response_to_pydict(py, resp)+ }++ /// Read a commit's metadata or a blob's bytes at a path.+ #[pyo3(signature = (**kwargs))]+ fn git_show(+ &self,+ py: Python<'_>,+ kwargs: Option<&Bound<'_, PyDict>>,+ ) -> PyResult<Py<PyAny>> {+ let svc = self.git_service.clone().ok_or_else(|| {+ git::new_py_err_pub(py, "AGFSNotSupportedError", "git feature disabled".into())+ })?;+ let empty = PyDict::new(py);+ let kw = kwargs.unwrap_or(&empty);+ let req = git::parse_show_request(kw)?;+ let resp = py_detach_blocking(py, move || self.rt.block_on(svc.show(req)))+ .map_err(|e| git::map_git_error(py, e))?;+ git::show_response_to_pydict(py, resp)+ }+/// Get client capabilities.fn get_capabilities(&self) -> PyResult<HashMap<String, Py<PyAny>>> {Python::attach(|py| {diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.tomlindex 64c1db03a..8ea09680c 100644--- a/crates/ragfs/Cargo.toml+++ b/crates/ragfs/Cargo.toml@@ -35,6 +35,17 @@ serde_json = "1.0"# Loggingtracing = "0.1"+# Git (gitoxide)+gix-hash = "0.14"+gix-object = "0.42"+gix-features = { version = "0.38", features = ["zlib"] }+gix-actor = "0.31"+gix-date = "0.8"++# Git backend dependencies+dashmap = "5.0"+flate2 = "1.0"+# Path handling and filesystempath-clean = "1.0"@@ -90,6 +101,14 @@ grep-searcher = "0.1.16"[dev-dependencies]tempfile = "3.12"criterion = "0.5"+tokio = { version = "1.38", features = ["full"] }+toml = "0.8"+# Used by the S3/TOS git integration tests (crates/ragfs/tests/git_s3_integration.rs)+gix-hash = "0.14"+gix-object = "0.42"+bytes = "1.5"+serde_json = "1.0"+uuid = { version = "1.0", features = ["v4"] }[features]default = []diff --git a/crates/ragfs/src/git/backends/local.rs b/crates/ragfs/src/git/backends/local.rsnew file mode 100644index 000000000..3aeb7dbc0--- /dev/null+++ b/crates/ragfs/src/git/backends/local.rs@@ -0,0 +1,537 @@+//! Local filesystem backend for Git object and ref storage++use std::path::{Path, PathBuf};+use std::sync::atomic::{AtomicU64, Ordering};+use std::sync::Arc;++use async_trait::async_trait;+use bytes::Bytes;+use dashmap::DashMap;+use gix_hash::ObjectId;+use tokio::sync::Mutex;++use crate::git::error::{ObjectStoreError, RefStoreError};+use crate::git::index_store::{+ decode_index, encode_index, systemtime_to_ns, CommitIndex, IndexStore, IndexStoreError,+};+use crate::git::object_store::ObjectStore;+use crate::git::ref_store::RefStore;+use crate::git::util::validate_ref_name;++/// Per-process counter used to give each in-flight object write a unique temp+/// filename, preventing concurrent `put` calls from sharing one `.tmp`.+static TMP_SEQ: AtomicU64 = AtomicU64::new(0);++/// Local filesystem implementation of ObjectStore.+///+/// Stores objects in Git's standard loose object format:+/// `{base_dir}/{account}/objects/{aa}/{bb...}`+/// where `aa` is the first 2 hex chars of the oid, and `bb...` is the rest.+pub struct LocalObjectStore {+ base_dir: PathBuf,+}++impl LocalObjectStore {+ /// Create a new LocalObjectStore with the given base directory.+ pub fn new(base_dir: impl Into<PathBuf>) -> Self {+ Self {+ base_dir: base_dir.into(),+ }+ }++ /// Get the filesystem path for an object.+ fn object_path(&self, account: &str, oid: &ObjectId) -> PathBuf {+ let hex = oid.to_hex().to_string();+ self.base_dir+ .join(account)+ .join("objects")+ .join(&hex[..2])+ .join(&hex[2..])+ }+}++#[async_trait]+impl ObjectStore for LocalObjectStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: Bytes,+ ) -> Result<(), ObjectStoreError> {+ let path = self.object_path(account, oid);++ // Idempotent: if object already exists, do nothing+ if tokio::fs::try_exists(&path).await? {+ return Ok(());+ }++ // Ensure parent directory exists+ if let Some(parent) = path.parent() {+ tokio::fs::create_dir_all(parent).await?;+ }++ // Write to a unique temp file first, then rename for atomicity. A+ // per-process counter keeps the temp name unique so concurrent `put`+ // calls for the same not-yet-existing object don't share one `.tmp`+ // and clobber each other mid-write.+ let seq = TMP_SEQ.fetch_add(1, Ordering::Relaxed);+ let tmp_path = path.with_extension(format!("tmp.{}.{}", std::process::id(), seq));+ tokio::fs::write(&tmp_path, &zlib_body).await?;+ match tokio::fs::rename(&tmp_path, &path).await {+ Ok(()) => Ok(()),+ Err(e) => {+ // A racing `put` for the same object may have already produced+ // it. Idempotency holds as long as the object exists, so treat+ // that as success. Clean up our orphaned temp file regardless.+ let _ = tokio::fs::remove_file(&tmp_path).await;+ if tokio::fs::try_exists(&path).await.unwrap_or(false) {+ Ok(())+ } else {+ Err(e.into())+ }+ }+ }+ }++ async fn get(&self, account: &str, oid: &ObjectId) -> Result<Bytes, ObjectStoreError> {+ let path = self.object_path(account, oid);+ match tokio::fs::read(&path).await {+ Ok(bytes) => Ok(Bytes::from(bytes)),+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {+ Err(ObjectStoreError::NotFound(*oid))+ }+ Err(e) => Err(e.into()),+ }+ }++ async fn exists(&self, account: &str, oid: &ObjectId) -> Result<bool, ObjectStoreError> {+ let path = self.object_path(account, oid);+ tokio::fs::try_exists(&path)+ .await+ .map_err(ObjectStoreError::Io)+ }+}++/// Local filesystem implementation of RefStore.+///+/// Stores refs as plain text files with hex oid content, and uses:+/// - In-memory locks per (account, ref_name) for process-level serialization+/// - Atomic rename for filesystem-level atomicity+pub struct LocalRefStore {+ base_dir: PathBuf,+ locks: DashMap<(String, String), Arc<Mutex<()>>>,+}++impl LocalRefStore {+ /// Create a new LocalRefStore with the given base directory.+ pub fn new(base_dir: impl Into<PathBuf>) -> Self {+ Self {+ base_dir: base_dir.into(),+ locks: DashMap::new(),+ }+ }++ /// Get the filesystem path for a ref.+ fn ref_path(&self, account: &str, ref_name: &str) -> PathBuf {+ self.base_dir.join(account).join(ref_name)+ }++ /// Get or create a lock for the given (account, ref_name).+ fn get_lock(&self, account: &str, ref_name: &str) -> Arc<Mutex<()>> {+ self.locks+ .entry((account.to_string(), ref_name.to_string()))+ .or_insert_with(|| Arc::new(Mutex::new(())))+ .clone()+ }++ /// Read a ref from disk, returns None if not found.+ async fn read_ref_opt(path: &Path) -> Result<Option<ObjectId>, RefStoreError> {+ match tokio::fs::read_to_string(path).await {+ Ok(content) => {+ let trimmed = content.trim();+ let oid = trimmed.parse::<ObjectId>().map_err(|_| {+ RefStoreError::Backend(format!("invalid oid in ref file: {trimmed}"))+ })?;+ Ok(Some(oid))+ }+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),+ Err(e) => Err(e.into()),+ }+ }+}++#[async_trait]+impl RefStore for LocalRefStore {+ async fn read(&self, account: &str, ref_name: &str) -> Result<ObjectId, RefStoreError> {+ // Validate ref name+ validate_ref_name(ref_name)?;++ let path = self.ref_path(account, ref_name);+ Self::read_ref_opt(&path)+ .await?+ .ok_or_else(|| RefStoreError::NotFound(ref_name.to_string()))+ }++ async fn cas_update(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<(), RefStoreError> {+ // Validate ref name first+ validate_ref_name(ref_name)?;++ // Acquire per-ref lock to serialize concurrent updates+ let lock = self.get_lock(account, ref_name);+ let _guard = lock.lock().await;++ let path = self.ref_path(account, ref_name);++ // Check current value matches expected+ let actual = Self::read_ref_opt(&path).await?;+ if actual != expected {+ return Err(RefStoreError::Conflict { expected, actual });+ }++ // Ensure parent directory exists+ if let Some(parent) = path.parent() {+ tokio::fs::create_dir_all(parent).await?;+ }++ // Write to temp file then rename for atomicity+ let tmp_path = path.with_extension("tmp");+ tokio::fs::write(&tmp_path, format!("{}\n", new.to_hex())).await?;+ tokio::fs::rename(&tmp_path, &path).await?;++ Ok(())+ }++ async fn list(+ &self,+ account: &str,+ prefix: &str,+ ) -> Result<Vec<(String, ObjectId)>, RefStoreError> {+ let dir_path = self.base_dir.join(account).join(prefix);+ let mut result = Vec::new();++ // Walk the directory recursively+ let mut stack = vec![dir_path];++ while let Some(current_path) = stack.pop() {+ match tokio::fs::read_dir(¤t_path).await {+ Ok(mut entries) => {+ while let Some(entry) = entries.next_entry().await? {+ let entry_path = entry.path();+ if entry_path.is_dir() {+ stack.push(entry_path);+ } else {+ // It's a file - parse as ref+ if let Ok(ref_name) = entry_path.strip_prefix(self.base_dir.join(account))+ {+ if let Some(ref_name_str) = ref_name.to_str() {+ if let Ok(Some(oid)) = Self::read_ref_opt(&entry_path).await {+ result.push((ref_name_str.to_string(), oid));+ }+ }+ }+ }+ }+ }+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {+ // Directory doesn't exist - return empty list+ break;+ }+ Err(e) => return Err(e.into()),+ }+ }++ Ok(result)+ }+}++/// Local filesystem implementation of [`IndexStore`].+///+/// Persists each `(account, branch)` snapshot at+/// `{base_dir}/{account}/index/{branch}.json`. The branch component is+/// `validate_ref_name`-checked before any path is constructed to keep crafted+/// names from escaping the per-account directory.+///+/// All errors degrade to `Ok(None)` on `load`: missing file, decode failure,+/// version skew. Save uses tempfile + rename for atomicity, so a crash mid-+/// write leaves the previous snapshot intact.+pub struct LocalIndexStore {+ base_dir: PathBuf,+}++impl LocalIndexStore {+ /// Create a new `LocalIndexStore` rooted at `base_dir`. Per-account+ /// subdirectories are created lazily on first save.+ pub fn new(base_dir: impl Into<PathBuf>) -> Self {+ Self {+ base_dir: base_dir.into(),+ }+ }++ fn index_path(&self, account: &str, branch: &str) -> PathBuf {+ self.base_dir+ .join(account)+ .join("index")+ .join(format!("{branch}.json"))+ }+}++#[async_trait]+impl IndexStore for LocalIndexStore {+ async fn load(+ &self,+ account: &str,+ branch: &str,+ ) -> Result<Option<CommitIndex>, IndexStoreError> {+ validate_ref_name(branch)+ .map_err(|_| IndexStoreError::InvalidBranch(branch.to_string()))?;++ let path = self.index_path(account, branch);+ match tokio::fs::read(&path).await {+ Ok(bytes) => match decode_index(&bytes) {+ Ok(Some(mut idx)) => {+ // Stamp the index with its own on-disk mtime so the commit+ // path can apply the racy-clean guard. Same clock + same+ // granularity as the working-tree file mtimes it's compared+ // against. A stat failure leaves `saved_at_ns = None`+ // (conservative: every entry is then treated as racy).+ idx.saved_at_ns = tokio::fs::metadata(&path)+ .await+ .ok()+ .and_then(|m| m.modified().ok())+ .and_then(systemtime_to_ns);+ Ok(Some(idx))+ }+ Ok(None) => Ok(None),+ Err(_) => Ok(None),+ },+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),+ Err(e) => Err(e.into()),+ }+ }++ async fn save(+ &self,+ account: &str,+ branch: &str,+ index: &CommitIndex,+ ) -> Result<(), IndexStoreError> {+ validate_ref_name(branch)+ .map_err(|_| IndexStoreError::InvalidBranch(branch.to_string()))?;++ let bytes = encode_index(index)?;+ let path = self.index_path(account, branch);+ if let Some(parent) = path.parent() {+ tokio::fs::create_dir_all(parent).await?;+ }+ let tmp_path = path.with_extension("tmp");+ tokio::fs::write(&tmp_path, &bytes).await?;+ tokio::fs::rename(&tmp_path, &path).await?;+ Ok(())+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use tempfile::tempdir;++ #[tokio::test]+ async fn test_local_object_store_put_get_exists() {+ let dir = tempdir().unwrap();+ let store = LocalObjectStore::new(dir.path());++ let account = "test-account";+ let oid = "0123456789abcdef0123456789abcdef01234567".parse::<ObjectId>().unwrap();+ let body = Bytes::from("test content");++ // Initially doesn't exist+ assert!(!store.exists(account, &oid).await.unwrap());++ // Put object+ store.put(account, &oid, body.clone()).await.unwrap();++ // Now exists+ assert!(store.exists(account, &oid).await.unwrap());++ // Get object and verify+ let retrieved = store.get(account, &oid).await.unwrap();+ assert_eq!(retrieved, body);++ // Put again is idempotent+ store.put(account, &oid, body).await.unwrap();+ }++ #[tokio::test]+ async fn test_local_object_store_concurrent_put_same_oid() {+ let dir = tempdir().unwrap();+ let store = Arc::new(LocalObjectStore::new(dir.path()));++ let account = "test-account";+ let oid = "0123456789abcdef0123456789abcdef01234567".parse::<ObjectId>().unwrap();+ let body = Bytes::from("test content");++ // Many concurrent puts for the same not-yet-existing object must all+ // succeed: the unique temp name + rename-failure recheck preserves+ // idempotency under the race.+ let mut handles = Vec::new();+ for _ in 0..32 {+ let store = store.clone();+ let body = body.clone();+ handles.push(tokio::spawn(async move {+ store.put(account, &oid, body).await+ }));+ }+ for handle in handles {+ handle.await.unwrap().unwrap();+ }++ assert_eq!(store.get(account, &oid).await.unwrap(), body);+ }++ #[tokio::test]+ async fn test_local_ref_store_read_cas_list() {+ let dir = tempdir().unwrap();+ let store = LocalRefStore::new(dir.path());++ let account = "test-account";+ let ref_name = "refs/heads/main";+ let oid1 = "0123456789abcdef0123456789abcdef01234567".parse::<ObjectId>().unwrap();+ let oid2 = "fedcba9876543210fedcba9876543210fedcba98".parse::<ObjectId>().unwrap();++ // Initially not found+ assert!(matches!(+ store.read(account, ref_name).await,+ Err(RefStoreError::NotFound(_))+ ));++ // CAS from None should work+ store.cas_update(account, ref_name, None, oid1).await.unwrap();++ // Read should return oid1+ assert_eq!(store.read(account, ref_name).await.unwrap(), oid1);++ // CAS from oid1 to oid2 should work+ store.cas_update(account, ref_name, Some(oid1), oid2).await.unwrap();+ assert_eq!(store.read(account, ref_name).await.unwrap(), oid2);++ // CAS with wrong expected should fail+ let result = store.cas_update(account, ref_name, Some(oid1), oid1).await;+ assert!(matches!(result, Err(RefStoreError::Conflict { .. })));++ // List refs+ let refs = store.list(account, "refs/heads/").await.unwrap();+ assert_eq!(refs.len(), 1);+ assert_eq!(refs[0].0, "refs/heads/main");+ assert_eq!(refs[0].1, oid2);+ }++ #[tokio::test]+ async fn test_local_ref_store_concurrent_cas() {+ let dir = tempdir().unwrap();+ let store = Arc::new(LocalRefStore::new(dir.path()));++ let account = "test-account";+ let ref_name = "refs/heads/main";++ // Spawn multiple concurrent cas_update tasks+ let mut handles = Vec::new();+ for i in 0..10 {+ let store = store.clone();+ let oid = format!("{:040}", i).parse::<ObjectId>().unwrap();+ handles.push(tokio::spawn(async move {+ // Each task will try to CAS in a loop until it succeeds+ let mut attempts = 0;+ while attempts < 100 {+ let current = store.read(account, ref_name).await.ok();+ match store.cas_update(account, ref_name, current, oid).await {+ Ok(_) => return true,+ Err(RefStoreError::Conflict { .. }) => attempts += 1,+ Err(e) => panic!("unexpected error: {e}"),+ }+ }+ false+ }));+ }++ // All should succeed eventually+ for handle in handles {+ assert!(handle.await.unwrap());+ }+ }++ fn idx_oid(b: u8) -> ObjectId {+ let mut bytes = [0u8; 20];+ bytes.fill(b);+ ObjectId::from_bytes_or_panic(&bytes)+ }++ #[tokio::test]+ async fn local_index_store_round_trip() {+ let dir = tempdir().unwrap();+ let store = LocalIndexStore::new(dir.path());++ // Missing → None+ let loaded = store.load("acct", "main").await.unwrap();+ assert!(loaded.is_none());++ let mut entries = std::collections::HashMap::new();+ entries.insert(+ "resources/a.md".into(),+ crate::git::types::IndexEntry {+ size: 11,+ mtime_ns: 1_700_000_000_000_000_000,+ oid: idx_oid(0xAA),+ },+ );+ let idx = crate::git::index_store::CommitIndex {+ parent_oid: idx_oid(0xCC),+ entries,+ saved_at_ns: None,+ };++ store.save("acct", "main", &idx).await.unwrap();+ let loaded = store.load("acct", "main").await.unwrap().unwrap();+ // parent_oid + entries round-trip through the wire format unchanged.+ assert_eq!(loaded.parent_oid, idx.parent_oid);+ assert_eq!(loaded.entries, idx.entries);+ // saved_at_ns is NOT in the wire format — it is stamped from the index+ // file's own mtime on load, so a freshly-saved index loads with Some.+ assert!(+ loaded.saved_at_ns.is_some(),+ "load must stamp saved_at_ns from the index file mtime",+ );+ }++ #[tokio::test]+ async fn local_index_store_corruption_is_soft_miss() {+ let dir = tempdir().unwrap();+ let store = LocalIndexStore::new(dir.path());++ // Manually drop a malformed file at the expected path+ let path = dir.path().join("acct").join("index").join("main.json");+ tokio::fs::create_dir_all(path.parent().unwrap()).await.unwrap();+ tokio::fs::write(&path, b"definitely not json").await.unwrap();++ // Should be Ok(None), not Err+ assert!(store.load("acct", "main").await.unwrap().is_none());+ }++ #[tokio::test]+ async fn local_index_store_rejects_invalid_branch() {+ let dir = tempdir().unwrap();+ let store = LocalIndexStore::new(dir.path());++ // Path-traversal style branch name → InvalidBranch error+ let result = store.load("acct", "../escape").await;+ assert!(matches!(+ result,+ Err(crate::git::index_store::IndexStoreError::InvalidBranch(_))+ ));+ }+}diff --git a/crates/ragfs/src/git/backends/mod.rs b/crates/ragfs/src/git/backends/mod.rsnew file mode 100644index 000000000..834fc129c--- /dev/null+++ b/crates/ragfs/src/git/backends/mod.rs@@ -0,0 +1,11 @@+//! Git storage backends++pub mod local;++#[cfg(feature = "s3")]+pub mod s3;++pub use local::{LocalObjectStore, LocalRefStore};++#[cfg(feature = "s3")]+pub use s3::{CasMode, S3Config, S3ObjectStore, S3RefStore};diff --git a/crates/ragfs/src/git/backends/s3.rs b/crates/ragfs/src/git/backends/s3.rsnew file mode 100644index 000000000..62d78f62b--- /dev/null+++ b/crates/ragfs/src/git/backends/s3.rs@@ -0,0 +1,795 @@+//! S3 storage backend for Git objects and refs++use std::sync::Arc;++use async_trait::async_trait;+use aws_sdk_s3::config::BehaviorVersion;+use aws_sdk_s3::config::Credentials;+use aws_sdk_s3::config::Region;+use bytes::Bytes;+use gix_hash::ObjectId;++use crate::git::error::{ObjectStoreError, RefStoreError};+use crate::git::index_store::{+ decode_index, encode_index, CommitIndex, IndexStore, IndexStoreError,+};+use crate::git::object_store::ObjectStore;+use crate::git::ref_store::RefStore;+use crate::git::util::validate_ref_name;++/// CAS (Compare-and-Swap) mode for S3 ref updates.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum CasMode {+ /// Use S3's native conditional writes with If-Match and ETag.+ /// This requires the S3 backend to support ETag and conditional headers.+ Native,+ /// Use a distributed lock (e.g., Redis) for CAS.+ /// Not yet implemented - placeholder for future.+ #[allow(dead_code)]+ RedisLock,+}++/// S3 configuration for Git storage+#[derive(Debug, Clone)]+pub struct S3Config {+ /// S3 bucket name+ pub bucket: String,+ /// Key prefix for Git storage (e.g. "git/")+ pub prefix: String,+ /// Region (e.g. "us-east-1")+ pub region: String,+ /// Optional endpoint URL (for MinIO, LocalStack, TOS, etc.)+ pub endpoint: Option<String>,+ /// Optional access key ID+ pub access_key_id: Option<String>,+ /// Optional secret access key+ pub secret_access_key: Option<String>,+ /// Whether to use path-style addressing (bucket/key vs bucket.host/key)+ pub use_path_style: bool,+ /// CAS mode for ref updates+ pub cas_mode: CasMode,+}++impl Default for S3Config {+ fn default() -> Self {+ Self {+ bucket: String::new(),+ prefix: String::new(),+ region: "us-east-1".to_string(),+ endpoint: None,+ access_key_id: None,+ secret_access_key: None,+ use_path_style: true,+ cas_mode: CasMode::Native,+ }+ }+}++/// S3-based object store implementation+pub struct S3ObjectStore {+ client: Arc<aws_sdk_s3::Client>,+ bucket: String,+ prefix: String,+}++impl S3ObjectStore {+ /// Create a new S3ObjectStore from an existing S3 client+ pub fn new(client: Arc<aws_sdk_s3::Client>, bucket: String, prefix: String) -> Self {+ Self {+ client,+ bucket,+ prefix,+ }+ }++ /// Create a new S3ObjectStore from configuration+ pub async fn from_config(config: S3Config) -> Result<Self, ObjectStoreError> {+ let mut s3_config_builder = aws_sdk_s3::Config::builder()+ .behavior_version(BehaviorVersion::latest())+ .region(Region::new(config.region))+ .force_path_style(config.use_path_style);++ // Set endpoint if provided (MinIO, LocalStack, TOS)+ if let Some(ep) = config.endpoint {+ s3_config_builder = s3_config_builder.endpoint_url(ep);+ }++ // Set credentials if provided, otherwise SDK uses default chain+ if let (Some(ak), Some(sk)) = (config.access_key_id, config.secret_access_key) {+ let creds = Credentials::new(ak, sk, None, None, "ragfs-git");+ s3_config_builder = s3_config_builder.credentials_provider(creds);+ }++ let s3_config = s3_config_builder.build();+ let client = Arc::new(aws_sdk_s3::Client::from_conf(s3_config));++ Ok(Self::new(client, config.bucket, config.prefix))+ }++ /// Build the full S3 key for a Git object+ fn object_key(&self, account: &str, oid: &ObjectId) -> String {+ build_object_key(&self.prefix, account, oid)+ }+}++#[async_trait]+impl ObjectStore for S3ObjectStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: Bytes,+ ) -> Result<(), ObjectStoreError> {+ let key = self.object_key(account, oid);++ // Use If-None-Match: "*" to ensure idempotency - only write if not exists+ match self+ .client+ .put_object()+ .bucket(&self.bucket)+ .key(&key)+ .body(zlib_body.to_vec().into())+ .if_none_match("*")+ .send()+ .await+ {+ Ok(_) => Ok(()),+ Err(aws_sdk_s3::error::SdkError::ServiceError(err)) => {+ // Check if the error indicates object already exists+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("preconditionfailed")+ || err_str.to_lowercase().contains("412")+ || err_str.to_lowercase().contains("not modified")+ {+ // Object already exists - that's fine for idempotency+ Ok(())+ } else {+ Err(ObjectStoreError::Backend(format!(+ "S3 put error: {:?}",+ err+ )))+ }+ }+ Err(err) => Err(ObjectStoreError::Backend(format!("S3 put error: {:?}", err))),+ }+ }++ async fn get(&self, account: &str, oid: &ObjectId) -> Result<Bytes, ObjectStoreError> {+ let key = self.object_key(account, oid);++ match self+ .client+ .get_object()+ .bucket(&self.bucket)+ .key(&key)+ .send()+ .await+ {+ Ok(resp) => {+ let bytes = resp+ .body+ .collect()+ .await+ .map_err(|e| ObjectStoreError::Backend(format!("S3 read body error: {:?}", e)))?;+ Ok(Bytes::copy_from_slice(&bytes.to_vec()))+ }+ Err(err) => {+ // Check if the error indicates object not found+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("no_such_key")+ || err_str.to_lowercase().contains("404")+ {+ Err(ObjectStoreError::NotFound(*oid))+ } else {+ Err(ObjectStoreError::Backend(format!("S3 get error: {:?}", err)))+ }+ }+ }+ }++ async fn exists(&self, account: &str, oid: &ObjectId) -> Result<bool, ObjectStoreError> {+ let key = self.object_key(account, oid);++ match self+ .client+ .head_object()+ .bucket(&self.bucket)+ .key(&key)+ .send()+ .await+ {+ Ok(_) => Ok(true),+ Err(err) => {+ // Check if the error indicates object not found+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("not_found")+ || err_str.to_lowercase().contains("404")+ {+ Ok(false)+ } else {+ Err(ObjectStoreError::Backend(format!("S3 head error: {:?}", err)))+ }+ }+ }+ }+}++/// S3-based ref store implementation+pub struct S3RefStore {+ client: Arc<aws_sdk_s3::Client>,+ bucket: String,+ prefix: String,+ cas_mode: CasMode,+}++impl S3RefStore {+ /// Create a new S3RefStore from an existing S3 client+ pub fn new(client: Arc<aws_sdk_s3::Client>, bucket: String, prefix: String) -> Self {+ Self {+ client,+ bucket,+ prefix,+ cas_mode: CasMode::Native,+ }+ }++ /// Create a new S3RefStore with explicit CAS mode+ pub fn with_cas_mode(+ client: Arc<aws_sdk_s3::Client>,+ bucket: String,+ prefix: String,+ cas_mode: CasMode,+ ) -> Self {+ Self {+ client,+ bucket,+ prefix,+ cas_mode,+ }+ }++ /// Create a new S3RefStore from configuration+ pub async fn from_config(config: S3Config) -> Result<Self, RefStoreError> {+ let mut s3_config_builder = aws_sdk_s3::Config::builder()+ .behavior_version(BehaviorVersion::latest())+ .region(Region::new(config.region))+ .force_path_style(config.use_path_style);++ // Set endpoint if provided (MinIO, LocalStack, TOS)+ if let Some(ep) = config.endpoint {+ s3_config_builder = s3_config_builder.endpoint_url(ep);+ }++ // Set credentials if provided, otherwise SDK uses default chain+ if let (Some(ak), Some(sk)) = (config.access_key_id, config.secret_access_key) {+ let creds = Credentials::new(ak, sk, None, None, "ragfs-git");+ s3_config_builder = s3_config_builder.credentials_provider(creds);+ }++ let s3_config = s3_config_builder.build();+ let client = Arc::new(aws_sdk_s3::Client::from_conf(s3_config));++ Ok(Self::with_cas_mode(+ client,+ config.bucket,+ config.prefix,+ config.cas_mode,+ ))+ }++ /// Build the full S3 key for a Git ref+ fn ref_key(&self, account: &str, ref_name: &str) -> String {+ build_ref_key(&self.prefix, account, ref_name)+ }++ /// Read the current value of a ref, returning None if it doesn't exist+ async fn read_ref_opt(+ &self,+ account: &str,+ ref_name: &str,+ ) -> Result<Option<(ObjectId, Option<String>)>, RefStoreError> {+ let key = self.ref_key(account, ref_name);++ match self+ .client+ .get_object()+ .bucket(&self.bucket)+ .key(&key)+ .send()+ .await+ {+ Ok(resp) => {+ let etag = resp.e_tag;+ let bytes = resp+ .body+ .collect()+ .await+ .map_err(|e| RefStoreError::Backend(format!("S3 read body error: {:?}", e)))?;+ let vec_bytes = bytes.to_vec();+ let content = String::from_utf8_lossy(&vec_bytes);+ let oid = parse_ref_oid(&content)?;+ Ok(Some((oid, etag)))+ }+ Err(err) => {+ // Check if the error indicates ref not found+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("no_such_key")+ || err_str.to_lowercase().contains("404")+ {+ Ok(None)+ } else {+ Err(RefStoreError::Backend(format!("S3 get error: {:?}", err)))+ }+ }+ }+ }++ /// Perform native CAS with S3 conditional headers+ async fn cas_native(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<(), RefStoreError> {+ let key = self.ref_key(account, ref_name);++ // First, read to get the current value and ETag+ let (current_value, current_etag) = match self.read_ref_opt(account, ref_name).await? {+ Some((oid, etag)) => (Some(oid), etag),+ None => (None, None),+ };++ // Verify the expected value matches+ if current_value != expected {+ return Err(RefStoreError::Conflict {+ expected,+ actual: current_value,+ });+ }++ // Prepare the conditional put request+ let body = format!("{}\n", new.to_hex());+ let mut put_builder = self+ .client+ .put_object()+ .bucket(&self.bucket)+ .key(&key)+ .body(body.into_bytes().into());++ put_builder = match (current_etag, expected) {+ (Some(etag), Some(_)) => {+ // Existing ref - use If-Match with the current ETag+ put_builder.if_match(etag)+ }+ (None, None) => {+ // New ref - use If-None-Match: "*" to ensure it doesn't exist+ put_builder.if_none_match("*")+ }+ _ => {+ // This shouldn't happen after our check, but just in case+ return Err(RefStoreError::Conflict {+ expected,+ actual: current_value,+ });+ }+ };++ match put_builder.send().await {+ Ok(_) => Ok(()),+ Err(aws_sdk_s3::error::SdkError::ServiceError(err)) => {+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("preconditionfailed")+ || err_str.to_lowercase().contains("412")+ {+ // Conditional check failed - re-read and report conflict+ let actual = self.read_ref_opt(account, ref_name).await?.map(|(oid, _)| oid);+ Err(RefStoreError::Conflict { expected, actual })+ } else {+ Err(RefStoreError::Backend(format!("S3 put error: {:?}", err)))+ }+ }+ Err(err) => Err(RefStoreError::Backend(format!("S3 put error: {:?}", err))),+ }+ }+}++#[async_trait]+impl RefStore for S3RefStore {+ async fn read(&self, account: &str, ref_name: &str) -> Result<ObjectId, RefStoreError> {+ // Validate ref name+ validate_ref_name(ref_name)?;++ self.read_ref_opt(account, ref_name)+ .await?+ .map(|(oid, _)| oid)+ .ok_or_else(|| RefStoreError::NotFound(ref_name.to_string()))+ }++ async fn cas_update(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<(), RefStoreError> {+ // Validate ref name first+ validate_ref_name(ref_name)?;++ match self.cas_mode {+ CasMode::Native => {+ self.cas_native(account, ref_name, expected, new).await+ }+ CasMode::RedisLock => {+ // Redis lock mode not yet implemented+ Err(RefStoreError::Backend(+ "RedisLock CAS mode not yet implemented".to_string(),+ ))+ }+ }+ }++ async fn list(+ &self,+ account: &str,+ prefix: &str,+ ) -> Result<Vec<(String, ObjectId)>, RefStoreError> {+ let key_prefix = self.ref_key(account, prefix);+ let key_prefix = if key_prefix.ends_with('/') {+ key_prefix+ } else {+ format!("{}/", key_prefix)+ };++ let mut result = Vec::new();+ let mut continuation_token = None;++ loop {+ let mut req = self+ .client+ .list_objects_v2()+ .bucket(&self.bucket)+ .prefix(&key_prefix);++ if let Some(token) = continuation_token {+ req = req.continuation_token(token);+ }++ let resp = req+ .send()+ .await+ .map_err(|e| RefStoreError::Backend(format!("S3 list error: {:?}", e)))?;++ let next_token = resp.next_continuation_token().map(|s| s.to_string());++ for obj in resp.contents() {+ if let Some(key) = obj.key() {+ // Skip directory markers+ if key.ends_with('/') {+ continue;+ }++ // Strip the base prefix to get the ref name+ let base_prefix = self.ref_key(account, "");+ let ref_name = key.strip_prefix(&base_prefix).unwrap_or(key);++ // Read the ref value (without ETag)+ if let Ok(Some((oid, _))) = self.read_ref_opt(account, ref_name).await {+ result.push((ref_name.to_string(), oid));+ }+ }+ }++ if resp.is_truncated() == Some(true) {+ continuation_token = next_token;+ } else {+ break;+ }+ }++ Ok(result)+ }+}++/// S3-backed implementation of [`IndexStore`].+///+/// Stores each `(account, branch)` snapshot at+/// `{prefix}/{account}/index/{branch}.json`. The branch component is+/// `validate_ref_name`-checked before any key is built, so crafted branch+/// names cannot escape the per-account namespace.+///+/// Save uses a plain `put_object` (last-write-wins) — there is no CAS because+/// the index is a soft-state cache and correctness is enforced at load time+/// via the `parent_oid` check. Decode failures and `NoSuchKey` both surface+/// as `Ok(None)` from `load`.+pub struct S3IndexStore {+ client: Arc<aws_sdk_s3::Client>,+ bucket: String,+ prefix: String,+}++impl S3IndexStore {+ /// Create a new `S3IndexStore` from an existing S3 client.+ pub fn new(client: Arc<aws_sdk_s3::Client>, bucket: String, prefix: String) -> Self {+ Self {+ client,+ bucket,+ prefix,+ }+ }++ /// Create a new `S3IndexStore` from configuration. Reuses the same+ /// credential / endpoint setup as [`S3ObjectStore::from_config`].+ pub async fn from_config(config: S3Config) -> Result<Self, IndexStoreError> {+ let mut s3_config_builder = aws_sdk_s3::Config::builder()+ .behavior_version(BehaviorVersion::latest())+ .region(Region::new(config.region))+ .force_path_style(config.use_path_style);++ if let Some(ep) = config.endpoint {+ s3_config_builder = s3_config_builder.endpoint_url(ep);+ }++ if let (Some(ak), Some(sk)) = (config.access_key_id, config.secret_access_key) {+ let creds = Credentials::new(ak, sk, None, None, "ragfs-git");+ s3_config_builder = s3_config_builder.credentials_provider(creds);+ }++ let s3_config = s3_config_builder.build();+ let client = Arc::new(aws_sdk_s3::Client::from_conf(s3_config));++ Ok(Self::new(client, config.bucket, config.prefix))+ }++ fn index_key(&self, account: &str, branch: &str) -> String {+ build_index_key(&self.prefix, account, branch)+ }+}++#[async_trait]+impl IndexStore for S3IndexStore {+ async fn load(+ &self,+ account: &str,+ branch: &str,+ ) -> Result<Option<CommitIndex>, IndexStoreError> {+ validate_ref_name(branch)+ .map_err(|_| IndexStoreError::InvalidBranch(branch.to_string()))?;++ let key = self.index_key(account, branch);+ match self+ .client+ .get_object()+ .bucket(&self.bucket)+ .key(&key)+ .send()+ .await+ {+ Ok(resp) => {+ // Capture the object's last-modified time before consuming the+ // body — used to stamp the racy-clean guard's `saved_at_ns`.+ // S3 timestamps are second-granularity, which widens the racy+ // window to ~1s; that is the conservative (safe) direction.+ let last_modified_ns = resp.last_modified().and_then(|dt| {+ let secs = dt.secs();+ if secs < 0 {+ None+ } else {+ Some(secs as i128 * 1_000_000_000 + dt.subsec_nanos() as i128)+ }+ });+ let bytes = resp+ .body+ .collect()+ .await+ .map_err(|e| IndexStoreError::Backend(format!("S3 read body: {:?}", e)))?;+ match decode_index(&bytes.to_vec()) {+ Ok(Some(mut idx)) => {+ idx.saved_at_ns = last_modified_ns;+ Ok(Some(idx))+ }+ Ok(None) => Ok(None),+ Err(_) => Ok(None),+ }+ }+ Err(err) => {+ let err_str = format!("{:?}", err);+ if err_str.to_lowercase().contains("no_such_key")+ || err_str.to_lowercase().contains("404")+ {+ Ok(None)+ } else {+ Err(IndexStoreError::Backend(format!("S3 get error: {:?}", err)))+ }+ }+ }+ }++ async fn save(+ &self,+ account: &str,+ branch: &str,+ index: &CommitIndex,+ ) -> Result<(), IndexStoreError> {+ validate_ref_name(branch)+ .map_err(|_| IndexStoreError::InvalidBranch(branch.to_string()))?;++ let bytes = encode_index(index)?;+ let key = self.index_key(account, branch);+ self.client+ .put_object()+ .bucket(&self.bucket)+ .key(&key)+ .body(bytes.into())+ .send()+ .await+ .map_err(|e| IndexStoreError::Backend(format!("S3 put error: {:?}", e)))?;+ Ok(())+ }+}++/// Build the full S3 key for a Git object.+///+/// Layout: `{prefix}/{account}/objects/{aa}/{bb..}` where `aa` is the first two+/// hex chars of the object id. When `prefix` is empty the leading segment is+/// omitted. A trailing slash on `prefix` is ignored.+fn build_object_key(prefix: &str, account: &str, oid: &ObjectId) -> String {+ let hex = oid.to_hex().to_string();+ let prefix = prefix.trim_end_matches('/');+ if prefix.is_empty() {+ format!("{}/objects/{}/{}", account, &hex[..2], &hex[2..])+ } else {+ format!("{}/{}/objects/{}/{}", prefix, account, &hex[..2], &hex[2..])+ }+}++/// Build the full S3 key for a Git ref.+///+/// Layout: `{prefix}/{account}/{ref_name}`. When `prefix` is empty the leading+/// segment is omitted. A trailing slash on `prefix` is ignored.+fn build_ref_key(prefix: &str, account: &str, ref_name: &str) -> String {+ let prefix = prefix.trim_end_matches('/');+ if prefix.is_empty() {+ format!("{}/{}", account, ref_name)+ } else {+ format!("{}/{}/{}", prefix, account, ref_name)+ }+}++/// Parse the trimmed content of a ref blob into an [`ObjectId`].+///+/// Returns [`RefStoreError::Backend`] when the content is not a valid object id.+fn parse_ref_oid(content: &str) -> Result<ObjectId, RefStoreError> {+ let trimmed = content.trim();+ trimmed+ .parse::<ObjectId>()+ .map_err(|_| RefStoreError::Backend(format!("invalid oid in ref: {}", trimmed)))+}++/// Build the full S3 key for a persisted commit index.+///+/// Layout: `{prefix}/{account}/index/{branch}.json`. When `prefix` is empty+/// the leading segment is omitted. A trailing slash on `prefix` is ignored.+fn build_index_key(prefix: &str, account: &str, branch: &str) -> String {+ let prefix = prefix.trim_end_matches('/');+ if prefix.is_empty() {+ format!("{}/index/{}.json", account, branch)+ } else {+ format!("{}/{}/index/{}.json", prefix, account, branch)+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ /// A valid 40-char SHA-1 hex object id used across tests.+ const VALID_OID_HEX: &str = "0123456789abcdef0123456789abcdef01234567";++ #[test]+ fn test_cas_mode_variants() {+ assert_eq!(CasMode::Native, CasMode::Native);+ assert_ne!(CasMode::Native, CasMode::RedisLock);+ }++ #[test]+ fn test_s3_config_default() {+ let config = S3Config::default();+ assert_eq!(config.region, "us-east-1");+ assert_eq!(config.use_path_style, true);+ assert_eq!(config.cas_mode, CasMode::Native);+ }++ #[test]+ fn test_object_key_with_prefix() {+ let oid: ObjectId = VALID_OID_HEX.parse().unwrap();+ let key = build_object_key("git", "acct1", &oid);+ assert_eq!(+ key,+ "git/acct1/objects/01/23456789abcdef0123456789abcdef01234567"+ );+ }++ #[test]+ fn test_object_key_empty_prefix() {+ let oid: ObjectId = VALID_OID_HEX.parse().unwrap();+ let key = build_object_key("", "acct1", &oid);+ assert_eq!(+ key,+ "acct1/objects/01/23456789abcdef0123456789abcdef01234567"+ );+ }++ #[test]+ fn test_object_key_trailing_slash_prefix() {+ let oid: ObjectId = VALID_OID_HEX.parse().unwrap();+ // A trailing slash on the prefix must not produce a double slash.+ let key = build_object_key("git/", "acct1", &oid);+ assert_eq!(+ key,+ "git/acct1/objects/01/23456789abcdef0123456789abcdef01234567"+ );+ }++ #[test]+ fn test_ref_key_with_prefix() {+ let key = build_ref_key("git", "acct1", "refs/heads/main");+ assert_eq!(key, "git/acct1/refs/heads/main");+ }++ #[test]+ fn test_ref_key_empty_prefix() {+ let key = build_ref_key("", "acct1", "refs/heads/main");+ assert_eq!(key, "acct1/refs/heads/main");+ }++ #[test]+ fn test_ref_key_trailing_slash_prefix() {+ let key = build_ref_key("git/", "acct1", "refs/heads/main");+ assert_eq!(key, "git/acct1/refs/heads/main");+ }++ #[test]+ fn test_parse_ref_oid_valid() {+ let oid = parse_ref_oid(VALID_OID_HEX).unwrap();+ assert_eq!(oid.to_hex().to_string(), VALID_OID_HEX);+ }++ #[test]+ fn test_parse_ref_oid_valid_with_whitespace() {+ // Ref blobs are commonly written with a trailing newline.+ let oid = parse_ref_oid(&format!(" {}\n", VALID_OID_HEX)).unwrap();+ assert_eq!(oid.to_hex().to_string(), VALID_OID_HEX);+ }++ #[test]+ fn test_parse_ref_oid_invalid_non_hex() {+ let err = parse_ref_oid("not-a-valid-oid").unwrap_err();+ assert!(matches!(err, RefStoreError::Backend(_)));+ }++ #[test]+ fn test_parse_ref_oid_invalid_wrong_length() {+ // Valid hex but too short to be a SHA-1 object id.+ let err = parse_ref_oid("0123abcd").unwrap_err();+ assert!(matches!(err, RefStoreError::Backend(_)));+ }++ #[test]+ fn test_index_key_with_prefix() {+ let key = build_index_key("git", "acct1", "main");+ assert_eq!(key, "git/acct1/index/main.json");+ }++ #[test]+ fn test_index_key_empty_prefix() {+ let key = build_index_key("", "acct1", "main");+ assert_eq!(key, "acct1/index/main.json");+ }++ #[test]+ fn test_index_key_trailing_slash_prefix() {+ let key = build_index_key("git/", "acct1", "main");+ assert_eq!(key, "git/acct1/index/main.json");+ }+}diff --git a/crates/ragfs/src/git/commit.rs b/crates/ragfs/src/git/commit.rsnew file mode 100644index 000000000..ec19ee538--- /dev/null+++ b/crates/ragfs/src/git/commit.rs@@ -0,0 +1,107 @@+//! Git commit object construction.++use gix_hash::ObjectId;+use gix_object::{bstr::BString, Commit, WriteTo};++use crate::git::error::ObjectStoreError;+use crate::git::object_store::ObjectStore;+use crate::git::util::write_object;++/// Build a `gix_object::Commit` and write it via the existing `write_object`+/// helper. Uses `gix_date::Time::now_local_or_utc()` for both author and+/// committer timestamps. Returns the new commit's ObjectId.+pub async fn write_commit(+ store: &dyn ObjectStore,+ account: &str,+ tree: ObjectId,+ parents: Vec<ObjectId>,+ author_name: &str,+ author_email: &str,+ message: &str,+) -> Result<ObjectId, ObjectStoreError> {+ let now = gix_date::Time::now_local_or_utc();+ let actor = gix_actor::Signature {+ name: author_name.into(),+ email: author_email.into(),+ time: now,+ };+ let commit = Commit {+ tree,+ parents: parents.into(),+ author: actor.clone(),+ committer: actor,+ encoding: None,+ message: BString::from(message),+ extra_headers: Vec::new(),+ };+ let mut buf = Vec::with_capacity(256);+ commit+ .write_to(&mut buf)+ .map_err(|e| ObjectStoreError::Backend(format!("commit encode: {e}")))?;+ write_object(store, account, gix_object::Kind::Commit, &buf).await+}++#[cfg(test)]+mod tests {+ use super::*;++ #[tokio::test]+ async fn test_write_commit_round_trip_no_parent() {+ use tempfile::tempdir;+ use crate::git::backends::local::LocalObjectStore;+ use crate::git::util::{read_object, parse_object_header};+ use gix_object::bstr::ByteSlice;++ let dir = tempdir().unwrap();+ let store = LocalObjectStore::new(dir.path());++ let tree = gix_hash::ObjectId::empty_tree(gix_hash::Kind::Sha1);+ let oid = write_commit(+ &store, "acct",+ tree,+ vec![], // root commit, no parents+ "alice", "[email protected]",+ "init",+ ).await.unwrap();++ let raw = read_object(&store, "acct", &oid).await.unwrap();+ let (kind, _, hdr) = parse_object_header(&raw).unwrap();+ assert_eq!(kind, gix_object::Kind::Commit);+ let parsed = gix_object::CommitRef::from_bytes(&raw[hdr..]).unwrap();+ assert_eq!(parsed.tree(), tree);+ assert_eq!(parsed.parents().count(), 0);+ assert_eq!(parsed.message, b"init".as_bstr());+ assert_eq!(parsed.author.name, b"alice".as_bstr());+ assert_eq!(parsed.author.email, b"[email protected]".as_bstr());+ }++ #[tokio::test]+ async fn test_write_commit_with_parent() {+ use tempfile::tempdir;+ use crate::git::backends::local::LocalObjectStore;+ use crate::git::util::{read_object, parse_object_header};++ let dir = tempdir().unwrap();+ let store = LocalObjectStore::new(dir.path());++ let tree = gix_hash::ObjectId::empty_tree(gix_hash::Kind::Sha1);+ let parent = gix_hash::ObjectId::from_hex(+ b"1234567890abcdef1234567890abcdef12345678"+ ).unwrap();++ let oid = write_commit(+ &store, "acct",+ tree,+ vec![parent],+ "bob", "[email protected]",+ "child commit",+ ).await.unwrap();++ let raw = read_object(&store, "acct", &oid).await.unwrap();+ let (_, _, hdr) = parse_object_header(&raw).unwrap();+ let parsed = gix_object::CommitRef::from_bytes(&raw[hdr..]).unwrap();+ let parents: Vec<_> = parsed.parents().collect();+ assert_eq!(parents.len(), 1);+ assert_eq!(parents[0], parent);+ }+}diff --git a/crates/ragfs/src/git/config.rs b/crates/ragfs/src/git/config.rsnew file mode 100644index 000000000..29bcf2b95--- /dev/null+++ b/crates/ragfs/src/git/config.rs@@ -0,0 +1,189 @@+//! Git module config types loaded from the [git] section of the binding TOML.++use serde::Deserialize;++#[derive(Debug, Clone, Deserialize)]+pub struct GitConfig {+ #[serde(default)]+ pub enabled: bool,+ #[serde(default = "default_backend")]+ pub backend: String,+ #[serde(default = "default_branch")]+ pub default_branch: String,+ #[serde(default = "default_author_name")]+ pub author_name: String,+ #[serde(default = "default_author_email")]+ pub author_email: String,++ #[serde(default)]+ pub local: Option<GitLocalConfig>,+ #[serde(default)]+ pub s3: Option<GitS3ConfigPy>,++ #[serde(default)]+ pub tuning: GitTuningConfig,+}++#[derive(Debug, Clone, Deserialize)]+pub struct GitLocalConfig {+ pub base_dir: String,+}++#[derive(Debug, Clone, Deserialize)]+pub struct GitS3ConfigPy {+ pub bucket: String,+ #[serde(default = "default_s3_prefix")]+ pub prefix: String,+ pub region: String,+ #[serde(default)]+ pub endpoint: String,+ #[serde(default)]+ pub access_key: Option<String>,+ #[serde(default)]+ pub secret_key: Option<String>,+ #[serde(default = "default_cas_mode")]+ pub cas_mode: String,+ #[serde(default)]+ pub redis_lock_url: Option<String>,+ #[serde(default = "default_true")]+ pub use_path_style: bool,+}++#[derive(Debug, Clone, Deserialize)]+pub struct GitTuningConfig {+ #[serde(default = "default_upload_concurrency")]+ pub upload_concurrency: usize,+ #[serde(default = "default_restore_concurrency")]+ pub restore_concurrency: usize,+ #[serde(default = "default_ref_cas_max_retry")]+ pub ref_cas_max_retry: u32,+ #[serde(default = "default_ref_cas_backoff_ms")]+ pub ref_cas_backoff_ms: u64,+ /// Enable Fast Path 1: skip read+SHA-1 for files whose `(size, mtime_ns)`+ /// match the previous commit's persisted index. Defaults to `true`; set+ /// to `false` to force the slow path on every commit (useful for tests+ /// and for environments with unreliable mtimes).+ #[serde(default = "default_true")]+ pub commit_index_enabled: bool,+ /// Enable Fast Path 3: on the commit slow path, run an `exists()` precheck+ /// before compressing and putting a blob, skipping the write when the+ /// object already exists. Defaults to `true`. `put` is idempotent, so this+ /// only affects backend call counts, never commit results.+ #[serde(default = "default_true")]+ pub blob_exists_precheck_enabled: bool,+}++impl Default for GitTuningConfig {+ fn default() -> Self {+ Self {+ upload_concurrency: default_upload_concurrency(),+ restore_concurrency: default_restore_concurrency(),+ ref_cas_max_retry: default_ref_cas_max_retry(),+ ref_cas_backoff_ms: default_ref_cas_backoff_ms(),+ commit_index_enabled: default_true(),+ blob_exists_precheck_enabled: default_true(),+ }+ }+}++fn default_backend() -> String {+ "local".to_string()+}+fn default_branch() -> String {+ "main".to_string()+}+fn default_author_name() -> String {+ "openviking-bot".to_string()+}+fn default_author_email() -> String {+ "[email protected]".to_string()+}+fn default_s3_prefix() -> String {+ ".ovgit".to_string()+}+fn default_cas_mode() -> String {+ "native".to_string()+}+fn default_upload_concurrency() -> usize {+ 64+}+fn default_restore_concurrency() -> usize {+ 32+}+fn default_ref_cas_max_retry() -> u32 {+ 3+}+fn default_ref_cas_backoff_ms() -> u64 {+ 50+}+fn default_true() -> bool {+ true+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn parses_minimal_local_config() {+ let toml_src = r#"+ enabled = true+ backend = "local"++ [local]+ base_dir = "/tmp/ov-git"+ "#;+ let cfg: GitConfig = toml::from_str(toml_src).unwrap();+ assert!(cfg.enabled);+ assert_eq!(cfg.backend, "local");+ assert_eq!(cfg.default_branch, "main");+ assert_eq!(cfg.author_name, "openviking-bot");+ assert_eq!(cfg.author_email, "[email protected]");+ assert_eq!(cfg.local.as_ref().unwrap().base_dir, "/tmp/ov-git");+ assert!(cfg.s3.is_none());+ assert_eq!(cfg.tuning.upload_concurrency, 64);+ assert_eq!(cfg.tuning.restore_concurrency, 32);+ assert_eq!(cfg.tuning.ref_cas_max_retry, 3);+ assert_eq!(cfg.tuning.ref_cas_backoff_ms, 50);+ assert!(cfg.tuning.commit_index_enabled);+ assert!(cfg.tuning.blob_exists_precheck_enabled);+ }++ #[test]+ fn parses_s3_config_with_overrides() {+ let toml_src = r#"+ enabled = true+ backend = "s3"+ default_branch = "trunk"+ author_name = "alice"+ author_email = "[email protected]"++ [s3]+ bucket = "ov-bucket"+ region = "us-west-2"+ endpoint = "https://s3.example.com"+ access_key = "AKxxx"+ secret_key = "SKxxx"++ [tuning]+ upload_concurrency = 128+ "#;+ let cfg: GitConfig = toml::from_str(toml_src).unwrap();+ assert_eq!(cfg.backend, "s3");+ assert_eq!(cfg.default_branch, "trunk");+ let s3 = cfg.s3.as_ref().unwrap();+ assert_eq!(s3.bucket, "ov-bucket");+ assert_eq!(s3.prefix, ".ovgit");+ assert_eq!(s3.region, "us-west-2");+ assert_eq!(s3.cas_mode, "native");+ assert_eq!(cfg.tuning.upload_concurrency, 128);+ assert_eq!(cfg.tuning.restore_concurrency, 32);+ }++ #[test]+ fn defaults_when_section_minimal() {+ let cfg: GitConfig = toml::from_str("").unwrap();+ assert!(!cfg.enabled);+ assert_eq!(cfg.backend, "local");+ }+}diff --git a/crates/ragfs/src/git/enumerate.rs b/crates/ragfs/src/git/enumerate.rsnew file mode 100644index 000000000..088d877e5--- /dev/null+++ b/crates/ragfs/src/git/enumerate.rs@@ -0,0 +1,405 @@+//! VFS enumeration with pruning rules from design §4.2.+//!+//! Walks an account's VFS subtree at `/local/{account}` and returns+//! account-relative paths of files that must be included in a Git snapshot.+//!+//! Pruning rules (verbatim from design §4.2):+//!+//! | Skip if account-relative path matches | Reason |+//! |---|---|+//! | First path segment ∈ {`_system`, `tasks`, `temp`, `queue`, `upload`} | Internal scopes + runtime locks |+//! | Any segment equals `.path.ovlock` OR starts with `.path.ovlock` | Runtime lock |+//! | File extension is `.faiss` or `.index`, OR path contains an `embedding_cache/` segment | Vector index — derived data |+//!+//! L0/L1 derived files (`.abstract.md`, `.overview.md`, `.relations.json`)+//! are intentionally KEPT — design §4.2 says they belong in snapshots.++use std::sync::Arc;++use crate::core::filesystem::FileSystem;+use crate::git::error::GitError;++/// First-segment internal scope names that are pruned.+///+/// Combines `INTERNAL_SCOPES` (system/tasks/temp/queue/upload) and+/// `VikingFS._INTERNAL_NAMES` from the design.+const INTERNAL_FIRST_SEGMENTS: &[&str] = &["_system", "tasks", "temp", "queue", "upload"];++/// Returns true if this account-relative path must be excluded from commits.+///+/// `rel` is the path relative to the account root (no leading "/", no+/// "/local/{account}/" prefix). Examples of valid input:+/// - "resources/a.md"+/// - "_system/lock"+/// - ".path.ovlock"+pub fn prune_path(rel: &str) -> bool {+ if rel.is_empty() {+ return true;+ }++ let segments: Vec<&str> = rel.split('/').filter(|s| !s.is_empty()).collect();+ if segments.is_empty() {+ return true;+ }++ // Rule 1: first path segment in INTERNAL_FIRST_SEGMENTS+ if INTERNAL_FIRST_SEGMENTS.contains(&segments[0]) {+ 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"+ // (i.e. path contains an `embedding_cache/` segment).+ for seg in &segments[..segments.len().saturating_sub(1)] {+ if *seg == "embedding_cache" {+ return true;+ }+ }++ // Rule 3b: extension is .faiss or .index+ if let Some(last) = segments.last() {+ if last.ends_with(".faiss") || last.ends_with(".index") {+ return true;+ }+ }++ false+}++/// Enumerate every versionable file in an account's VFS subtree.+///+/// Returns paths relative to the account root (no leading "/", no+/// "/local/{account}/" prefix). Directories are filtered out; only file+/// entries that survive pruning are returned.+pub async fn collect_all(+ vfs: &Arc<dyn FileSystem>,+ account: &str,+) -> Result<Vec<String>, GitError> {+ collect_under(vfs, account, "").await+}++/// Enumerate every versionable file under an account-relative subdirectory.+///+/// `sub_path` is account-relative (no leading "/", no trailing "/"). An empty+/// `sub_path` enumerates the entire account tree (equivalent to+/// [`collect_all`]). Returned paths are account-relative and include the+/// `sub_path` prefix. Directories are filtered out; only file entries that+/// survive [`prune_path`] (applied to the account-relative form) are returned.+pub async fn collect_under(+ vfs: &Arc<dyn FileSystem>,+ account: &str,+ sub_path: &str,+) -> Result<Vec<String>, GitError> {+ let root = if sub_path.is_empty() {+ format!("/local/{}", account)+ } else {+ format!("/local/{}/{}", account, sub_path)+ };+ let account_prefix = format!("/local/{}/", account);++ let entries = vfs.tree_directory(&root, true, None, None).await?;++ let mut survivors = Vec::new();+ for entry in entries {+ if entry.info.is_dir {+ continue;+ }++ // Strip "/local/{account}/" so pruning sees account-relative paths.+ // If the entry doesn't carry that prefix, skip it (defensive — should+ // not happen for a well-formed VFS).+ let rel = match entry.path.strip_prefix(&account_prefix) {+ Some(r) => r,+ None => continue,+ };++ if prune_path(rel) {+ continue;+ }++ survivors.push(rel.to_string());+ }++ Ok(survivors)+}++#[cfg(test)]+mod tests {+ use super::*;+ use async_trait::async_trait;+ use std::collections::HashMap;+ use std::sync::Arc;++ use crate::core::errors::Result;+ use crate::core::filesystem::FileSystem;+ use crate::core::types::{FileInfo, TreeEntry, WriteFlag};++ /// In-test mock that directly overrides `tree_directory` to return a+ /// precomputed list of (path, is_dir). All other trait methods are+ /// unimplemented because `collect_all` only calls `tree_directory`.+ struct MockFS {+ /// Map: root path -> list of (absolute path, is_dir)+ entries_by_root: HashMap<String, Vec<(String, bool)>>,+ }++ impl MockFS {+ fn new(root: &str, entries: Vec<(&str, bool)>) -> Self {+ let mut map = HashMap::new();+ map.insert(+ root.to_string(),+ entries+ .into_iter()+ .map(|(p, d)| (p.to_string(), d))+ .collect(),+ );+ Self {+ entries_by_root: map,+ }+ }+ }++ #[async_trait]+ impl FileSystem for MockFS {+ async fn create(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn mkdir(&self, _path: &str, _mode: u32) -> Result<()> {+ unimplemented!()+ }+ async fn remove(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn remove_all(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn read(&self, _path: &str, _offset: u64, _size: u64) -> Result<Vec<u8>> {+ unimplemented!()+ }+ async fn write(+ &self,+ _path: &str,+ _data: &[u8],+ _offset: u64,+ _flags: WriteFlag,+ ) -> Result<u64> {+ unimplemented!()+ }+ async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ unimplemented!()+ }+ async fn stat(&self, _path: &str) -> Result<FileInfo> {+ unimplemented!()+ }+ async fn rename(&self, _old_path: &str, _new_path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn chmod(&self, _path: &str, _mode: u32) -> Result<()> {+ unimplemented!()+ }++ /// Override tree_directory to return precomputed entries, bypassing+ /// the default read_dir/stat-based recursion.+ async fn tree_directory(+ &self,+ path: &str,+ _show_hidden: bool,+ _node_limit: Option<usize>,+ _level_limit: Option<usize>,+ ) -> Result<Vec<TreeEntry>> {+ let raw = self.entries_by_root.get(path).cloned().unwrap_or_default();++ let prefix = if path == "/" {+ "/".to_string()+ } else {+ format!("{}/", path)+ };++ let mut out = Vec::new();+ for (full_path, is_dir) in raw {+ let rel_path = full_path+ .strip_prefix(&prefix)+ .unwrap_or(&full_path)+ .to_string();+ let name = full_path+ .rsplit('/')+ .next()+ .unwrap_or(&full_path)+ .to_string();+ let info = if is_dir {+ FileInfo::new_dir(name, 0o755)+ } else {+ FileInfo::new_file(name, 0, 0o644)+ };+ out.push(TreeEntry {+ path: full_path,+ rel_path,+ info,+ extra: HashMap::new(),+ });+ }+ Ok(out)+ }+ }++ #[tokio::test]+ async fn test_collect_all_prunes_internal_scopes_and_vector_indexes() {+ let mock = MockFS::new(+ "/local/acct",+ vec![+ ("/local/acct/resources/a.md", false),+ ("/local/acct/agent/b.py", false),+ ("/local/acct/_system/lock", false),+ ("/local/acct/tasks/job.json", false),+ ("/local/acct/temp/upload.bin", false),+ ("/local/acct/queue/x", false),+ ("/local/acct/upload/y", false),+ ("/local/acct/resources/x.faiss", false),+ ("/local/acct/resources/x.index", false),+ ("/local/acct/resources/embedding_cache/v.bin", false),+ ],+ );+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let mut got = collect_all(&fs, "acct").await.unwrap();+ got.sort();++ let mut expected = vec!["agent/b.py".to_string(), "resources/a.md".to_string()];+ expected.sort();++ assert_eq!(got, expected);+ }++ #[tokio::test]+ async fn test_collect_all_keeps_derived_l0_l1_files() {+ let mock = MockFS::new(+ "/local/acct",+ vec![+ ("/local/acct/resources/x.md", false),+ ("/local/acct/resources/x.md.abstract.md", false),+ ("/local/acct/resources/x.md.overview.md", false),+ ("/local/acct/resources/x.md.relations.json", false),+ ],+ );+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let mut got = collect_all(&fs, "acct").await.unwrap();+ got.sort();++ let mut expected = vec![+ "resources/x.md".to_string(),+ "resources/x.md.abstract.md".to_string(),+ "resources/x.md.overview.md".to_string(),+ "resources/x.md.relations.json".to_string(),+ ];+ expected.sort();++ assert_eq!(got, expected);+ }++ #[tokio::test]+ async fn test_collect_all_returns_account_relative_paths() {+ let mock = MockFS::new("/local/acct", vec![("/local/acct/resources/a.md", false)]);+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let got = collect_all(&fs, "acct").await.unwrap();+ assert_eq!(got, vec!["resources/a.md".to_string()]);+ // Defensive: ensure no absolute leakage.+ for p in &got {+ assert!(!p.starts_with('/'), "path should not be absolute: {}", p);+ assert!(+ !p.contains("/local/acct"),+ "path should not contain account prefix: {}",+ p+ );+ }+ }++ #[tokio::test]+ async fn test_collect_under_returns_paths_below_subdir_with_prefix() {+ let mock = MockFS::new(+ "/local/acct/resources",+ vec![+ ("/local/acct/resources/a.md", false),+ ("/local/acct/resources/sub/b.md", false),+ ("/local/acct/resources/x.faiss", false),+ ],+ );+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let mut got = collect_under(&fs, "acct", "resources").await.unwrap();+ got.sort();++ let mut expected = vec![+ "resources/a.md".to_string(),+ "resources/sub/b.md".to_string(),+ ];+ expected.sort();++ assert_eq!(got, expected);+ }++ #[tokio::test]+ async fn test_collect_under_empty_sub_path_equivalent_to_collect_all() {+ let mock = MockFS::new(+ "/local/acct",+ vec![+ ("/local/acct/resources/a.md", false),+ ("/local/acct/_system/lock", false),+ ],+ );+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let got_under = collect_under(&fs, "acct", "").await.unwrap();+ let got_all = collect_all(&fs, "acct").await.unwrap();+ assert_eq!(got_under, got_all);+ assert_eq!(got_under, vec!["resources/a.md".to_string()]);+ }++ #[tokio::test]+ async fn test_collect_under_applies_pruning_on_account_relative_form() {+ // A `_system` sub_path is itself a pruned prefix — every file under it+ // is pruned because the first account-relative segment is "_system".+ let mock = MockFS::new(+ "/local/acct/_system",+ vec![("/local/acct/_system/lock", false)],+ );+ let fs: Arc<dyn FileSystem> = Arc::new(mock);++ let got = collect_under(&fs, "acct", "_system").await.unwrap();+ assert!(got.is_empty(), "everything under _system must be pruned");+ }++ #[test]+ fn test_prune_path_table() {+ // Pruned+ assert!(prune_path("_system/lock"));+ assert!(prune_path("tasks/job.json"));+ assert!(prune_path("temp/x"));+ assert!(prune_path("queue/x"));+ assert!(prune_path("upload/x"));+ assert!(prune_path("resources/.path.ovlock"));+ assert!(prune_path(".path.ovlock"));+ assert!(prune_path("resources/x.faiss"));+ assert!(prune_path("resources/x.index"));+ assert!(prune_path("resources/embedding_cache/v.bin"));+ assert!(prune_path("agent/embedding_cache/something"));++ // Survivors+ assert!(!prune_path("resources/a.md"));+ assert!(!prune_path("agent/skills/b.py"));+ assert!(!prune_path("resources/x.md.abstract.md"));+ assert!(!prune_path("resources/x.md.overview.md"));+ assert!(!prune_path("resources/x.md.relations.json"));+ // "_systemfoo" is NOT "_system", must survive.+ assert!(!prune_path("_systemfoo/x"));+ // Per "any segment starting with .path.ovlock", ".path.ovlocking"+ // is pruned even though it isn't exactly ".path.ovlock".+ assert!(prune_path("resources/.path.ovlocking"));+ }+}diff --git a/crates/ragfs/src/git/error.rs b/crates/ragfs/src/git/error.rsnew file mode 100644index 000000000..12bd8b8b2--- /dev/null+++ b/crates/ragfs/src/git/error.rs@@ -0,0 +1,170 @@+//! Git module error types++use thiserror::Error;++/// Errors from ObjectStore operations+#[derive(Debug, Error)]+pub enum ObjectStoreError {+ /// Object not found+ #[error("object not found: {0}")]+ NotFound(gix_hash::ObjectId),++ /// I/O error+ #[error("i/o error: {0}")]+ Io(#[from] std::io::Error),++ /// Zlib decompression error+ #[error("zlib error: {0}")]+ Zlib(String),++ /// ObjectId mismatch (content integrity check failed)+ #[error("oid mismatch: expected {expected}, got {actual}")]+ OidMismatch {+ expected: gix_hash::ObjectId,+ actual: gix_hash::ObjectId,+ },++ /// Backend-specific error+ #[error("backend error: {0}")]+ Backend(String),+}++/// Errors from RefStore operations+#[derive(Debug, Error)]+pub enum RefStoreError {+ /// Ref not found+ #[error("ref not found: {0}")]+ NotFound(String),++ /// CAS conflict - expected value didn't match actual+ #[error("cas conflict: expected {expected:?}, actual {actual:?}")]+ Conflict {+ expected: Option<gix_hash::ObjectId>,+ actual: Option<gix_hash::ObjectId>,+ },++ /// Invalid ref name (failed validation)+ #[error("invalid ref name: {0}")]+ InvalidName(String),++ /// I/O error+ #[error("i/o error: {0}")]+ Io(#[from] std::io::Error),++ /// Backend-specific error+ #[error("backend error: {0}")]+ Backend(String),+}++/// Top-level Git service error+#[derive(Debug, Error)]+pub enum GitError {+ /// ObjectStore error+ #[error("object store error: {0}")]+ ObjectStore(#[from] ObjectStoreError),++ /// RefStore error+ #[error("ref store error: {0}")]+ RefStore(#[from] RefStoreError),++ /// Path not found in tree+ #[error("path not found in tree: {0}")]+ PathNotFound(String),++ /// Path exists in tree but resolves to a directory (tree), not a blob.+ /// Returned by `show()` when the caller asked for blob bytes at a path+ /// that turned out to be a subdirectory.+ #[error("path is a directory, not a file: {0}")]+ PathIsDirectory(String),++ /// `project_dir` is an empty / malformed path string.+ /// Same validation as `TreeEditor::upsert`: must be non-empty, no leading+ /// or trailing `/`, no empty components, no `.` / `..` / backslash /+ /// control char components.+ #[error("invalid project_dir: {0}")]+ InvalidProjectDir(String),++ /// A user-supplied relative path in `CommitRequest.paths` or+ /// `ShowRequest.path` failed validation. The Rust GitService is a native+ /// boundary (PyO3 bindings, future SDK callers), so it cannot rely on+ /// upstream HTTP / SDK layers to have already normalized away `..` /+ /// `\` / control chars. Rejected before any VFS or object-store I/O.+ #[error("invalid path: {0}")]+ InvalidPath(String),++ /// The requested `project_dir` does not resolve to a subtree in the+ /// referenced commit's tree (either the path is missing entirely or it+ /// resolves to a blob rather than a tree).+ #[error("project_dir {project_dir:?} not found as a subtree in commit {commit}")]+ SubtreeNotFoundInCommit {+ project_dir: String,+ commit: gix_hash::ObjectId,+ },++ /// Invalid account ID+ #[error("invalid account id: {0}")]+ InvalidAccountId(String),++ /// Concurrent commit conflict+ #[error("concurrent commit: ref {ref_name} changed during commit (expected {expected:?}, actual {actual:?})")]+ ConcurrentCommit {+ ref_name: String,+ expected: Option<gix_hash::ObjectId>,+ actual: Option<gix_hash::ObjectId>,+ },++ /// `restore()` advanced the branch ref to the new commit, but at least+ /// one per-path VFS write or delete failed afterwards. The branch ref+ /// already points at `new_commit_oid`; the caller must use the payload+ /// to drive reindex of the paths that did reach the VFS and report the+ /// failures to whoever needs to retry them.+ #[error(+ "restore writeback partial: {writes_failed} write(s) and {deletes_failed} delete(s) failed after ref advanced to {new_commit}",+ writes_failed = .0.failed_writes.len(),+ deletes_failed = .0.failed_deletes.len(),+ new_commit = .0.new_commit_oid,+ )]+ RestoreWritebackPartial(Box<crate::git::types::RestoreWritebackPartial>),++ /// Blob too large+ #[error("blob too large: {size} bytes exceeds limit {limit} bytes")]+ BlobTooLarge { size: u64, limit: u64 },++ /// Too many files in commit+ #[error("too many files: {count} exceeds limit {limit}")]+ TooManyFiles { count: usize, limit: usize },++ /// Feature not enabled+ #[error("git feature not enabled")]+ FeatureDisabled,++ /// Corrupted object+ #[error("corrupted object: {0}")]+ CorruptedObject(String),++ /// No object matched the abbreviated OID prefix+ #[error("no commit found matching OID prefix {prefix}")]+ OidPrefixNotFound { prefix: String },++ /// Multiple objects matched the abbreviated OID prefix+ #[error("ambiguous OID prefix {prefix} matches {count} commits: {candidates}")]+ AmbiguousOid {+ prefix: String,+ count: usize,+ candidates: String,+ },++ /// Other error+ #[error("{0}")]+ Other(String),++ /// Vfs error wrapper+ #[error("vfs: {0}")]+ Vfs(String),+}++impl From<crate::core::errors::Error> for GitError {+ fn from(e: crate::core::errors::Error) -> Self {+ GitError::Vfs(e.to_string())+ }+}diff --git a/crates/ragfs/src/git/index_store.rs b/crates/ragfs/src/git/index_store.rsnew file mode 100644index 000000000..191e0efea--- /dev/null+++ b/crates/ragfs/src/git/index_store.rs@@ -0,0 +1,279 @@+//! Persistent commit index ("Fast Path 1" stat cache).+//!+//! After each successful commit, `GitService::commit` saves a snapshot of+//! `(path -> size, mtime_ns, oid)` for every file that was part of the+//! resulting tree. The next commit can then skip the read+SHA-1+write path+//! for any file whose `(size, mtime_ns)` match the cached entry — saving+//! the expensive blob materialization that produces the same OID we already+//! have.+//!+//! Correctness guard: every saved index records its `parent_oid` (the commit+//! the index reflects). On load, if `parent_oid != prev_head` (concurrent+//! commit, branch switch, first run) the cache is silently discarded and+//! commit proceeds via the slow path. Cache misses are *always* a soft+//! failure — we never produce an incorrect commit because of a stale or+//! corrupt index.+//!+//! Racy-clean guard: `(size, mtime_ns)` alone cannot distinguish "unchanged"+//! from "changed to the same size within the same filesystem clock tick as+//! the last commit". To close that window (the classic git "racy clean"+//! problem) the store records *when the index was written* in+//! [`CommitIndex::saved_at_ns`] — populated at `load()` time from the index+//! file's own mtime (local) or object `last_modified` (S3), i.e. the same+//! clock and granularity as the working-tree file mtimes it is compared+//! against. A cache entry is only trusted when its `mtime_ns` is strictly+//! older than `saved_at_ns`; an entry whose mtime is in the same tick as (or+//! newer than) the index write is "racy" and forced down the slow path. This+//! costs at most one extra read per file, and only for files that shared a+//! clock tick with a commit — steady-state Fast Path 1 is unaffected.+//!+//! The wire format is JSON for debuggability. OIDs are stored as 40-char hex.+//! Any deserialization or backend error is mapped to `Ok(None)` on `load()`,+//! and `save()` failures are logged by the caller (the commit itself has+//! already succeeded by the time we save).+//!+//! Per-(account, branch). The branch component is `validate_ref_name`-checked+//! before any path is constructed, so attempts at path traversal via crafted+//! branch names are rejected.++use std::collections::HashMap;+use std::time::SystemTime;++use async_trait::async_trait;+use gix_hash::ObjectId;+use serde::{Deserialize, Serialize};+use thiserror::Error;++use crate::git::types::IndexEntry;++/// Convert a [`SystemTime`] to nanoseconds since the Unix epoch, matching the+/// `i128` representation used for `IndexEntry::mtime_ns`. Returns `None` for+/// pre-epoch times (which the racy-clean guard treats conservatively). Shared+/// by the `IndexStore` backends to stamp [`CommitIndex::saved_at_ns`] from the+/// index file's own modification time on load.+pub fn systemtime_to_ns(t: SystemTime) -> Option<i128> {+ t.duration_since(SystemTime::UNIX_EPOCH)+ .ok()+ .map(|d| d.as_nanos() as i128)+}++/// Snapshot of the working tree's `(size, mtime_ns, oid)` after the commit+/// identified by `parent_oid`.+///+/// `entries` is keyed by account-relative path (same form as `CommitRequest::paths`).+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct CommitIndex {+ /// Commit OID this snapshot reflects. Used to invalidate the cache when+ /// the branch head has moved (concurrent commit, branch switch, etc.).+ pub parent_oid: ObjectId,+ /// Account-relative path → cached `(size, mtime_ns, oid)`.+ pub entries: HashMap<String, IndexEntry>,+ /// Wall-clock time (ns since epoch) the index file was written, as+ /// observed from the backend's own metadata at `load()` time. `None` for+ /// freshly-built (not-yet-persisted) indexes and when the backend cannot+ /// report a modification time. Used for the racy-clean guard: a cache+ /// entry whose `mtime_ns >= saved_at_ns` may have been modified within the+ /// same clock tick as the last commit and is forced down the slow path.+ /// Not part of the on-disk wire format — it is derived from the file's own+ /// timestamp on load.+ pub saved_at_ns: Option<i128>,+}++/// Error type returned by [`IndexStore`] operations. All error variants are+/// soft failures from the caller's perspective — `load()` callers map them to+/// `Ok(None)` and `save()` callers log and continue.+#[derive(Debug, Error)]+pub enum IndexStoreError {+ /// Underlying I/O error from the backend (filesystem, network, etc.).+ #[error("i/o error: {0}")]+ Io(#[from] std::io::Error),+ /// On-disk format could not be parsed (corruption, version skew, bad oid).+ #[error("decode error: {0}")]+ Decode(String),+ /// Branch component failed `validate_ref_name` (path-traversal guard).+ #[error("invalid branch name: {0}")]+ InvalidBranch(String),+ /// Non-I/O backend failure (e.g. S3 SDK error).+ #[error("backend error: {0}")]+ Backend(String),+}++/// Per-(account, branch) commit-index storage.+///+/// `load` returns `Ok(None)` for any "no usable index here" outcome — missing+/// file, decode failure, version mismatch, etc. The caller treats every miss+/// as "skip Fast Path 1, fall back to the full read/hash path".+///+/// `save` is fire-and-forget from the caller's perspective: the commit has+/// already succeeded; the worst-case cost of a save failure is one extra+/// slow-path commit next time.+#[async_trait]+pub trait IndexStore: Send + Sync + 'static {+ /// Load the latest persisted index for `(account, branch)`. Returns+ /// `Ok(None)` if no index has been written yet, or if the persisted bytes+ /// fail to decode (treated as a soft miss so commit falls back to the+ /// slow path).+ async fn load(+ &self,+ account: &str,+ branch: &str,+ ) -> Result<Option<CommitIndex>, IndexStoreError>;++ /// Persist `index` for `(account, branch)`, replacing any prior snapshot.+ /// Last-write-wins semantics — there is no CAS because the index is a+ /// soft-state cache; correctness is enforced at load time via the+ /// `parent_oid` check.+ async fn save(+ &self,+ account: &str,+ branch: &str,+ index: &CommitIndex,+ ) -> Result<(), IndexStoreError>;+}++// ---- Wire format ---------------------------------------------------------++/// Bumped only when a backwards-incompatible change to the layout ships.+/// Older readers see an unknown version and treat the file as absent.+const INDEX_FORMAT_VERSION: u32 = 1;++#[derive(Debug, Serialize, Deserialize)]+struct WireIndex {+ version: u32,+ parent_oid: String,+ entries: Vec<WireEntry>,+}++#[derive(Debug, Serialize, Deserialize)]+struct WireEntry {+ path: String,+ size: u64,+ mtime_ns: i128,+ oid: String,+}++/// Serialize a `CommitIndex` into the on-disk JSON wire format.+pub fn encode_index(index: &CommitIndex) -> Result<Vec<u8>, IndexStoreError> {+ let mut entries: Vec<WireEntry> = index+ .entries+ .iter()+ .map(|(path, e)| WireEntry {+ path: path.clone(),+ size: e.size,+ mtime_ns: e.mtime_ns,+ oid: e.oid.to_hex().to_string(),+ })+ .collect();+ // Sorted output → deterministic byte content for tests / hashing.+ entries.sort_by(|a, b| a.path.cmp(&b.path));+ let wire = WireIndex {+ version: INDEX_FORMAT_VERSION,+ parent_oid: index.parent_oid.to_hex().to_string(),+ entries,+ };+ serde_json::to_vec(&wire).map_err(|e| IndexStoreError::Decode(e.to_string()))+}++/// Decode the on-disk JSON wire format. An unknown `version` field returns+/// `Ok(None)`; malformed JSON or invalid OIDs return `Err(Decode)` (which+/// the trait `load()` callers also map to `None`).+pub fn decode_index(bytes: &[u8]) -> Result<Option<CommitIndex>, IndexStoreError> {+ let wire: WireIndex = match serde_json::from_slice(bytes) {+ Ok(w) => w,+ Err(e) => return Err(IndexStoreError::Decode(e.to_string())),+ };+ if wire.version != INDEX_FORMAT_VERSION {+ // Forward-compat: unknown version → silently treat as missing.+ return Ok(None);+ }+ let parent_oid = ObjectId::from_hex(wire.parent_oid.as_bytes())+ .map_err(|e| IndexStoreError::Decode(format!("parent_oid: {e}")))?;+ let mut entries = HashMap::with_capacity(wire.entries.len());+ for w in wire.entries {+ let oid = ObjectId::from_hex(w.oid.as_bytes())+ .map_err(|e| IndexStoreError::Decode(format!("entry oid {}: {e}", w.path)))?;+ entries.insert(+ w.path,+ IndexEntry {+ size: w.size,+ mtime_ns: w.mtime_ns,+ oid,+ },+ );+ }+ Ok(Some(CommitIndex {+ parent_oid,+ entries,+ // The wire format carries no timestamp; callers that need the+ // racy-clean guard populate `saved_at_ns` from the backing file's own+ // mtime after a successful decode.+ saved_at_ns: None,+ }))+}++#[cfg(test)]+mod tests {+ use super::*;++ fn oid_from_byte(b: u8) -> ObjectId {+ let mut bytes = [0u8; 20];+ bytes.fill(b);+ ObjectId::from_bytes_or_panic(&bytes)+ }++ #[test]+ fn round_trip_preserves_entries() {+ let mut entries = HashMap::new();+ entries.insert(+ "resources/a.md".into(),+ IndexEntry {+ size: 42,+ mtime_ns: 1_700_000_000_000_000_000,+ oid: oid_from_byte(0xAA),+ },+ );+ entries.insert(+ "agent/b.py".into(),+ IndexEntry {+ size: 7,+ mtime_ns: -1,+ oid: oid_from_byte(0xBB),+ },+ );+ let idx = CommitIndex {+ parent_oid: oid_from_byte(0xCC),+ entries,+ saved_at_ns: None,+ };+ let bytes = encode_index(&idx).unwrap();+ let decoded = decode_index(&bytes).unwrap().unwrap();+ assert_eq!(decoded, idx);+ }++ #[test]+ fn unknown_version_is_silent_miss() {+ let bogus = serde_json::json!({+ "version": 9999,+ "parent_oid": format!("{:040}", 0),+ "entries": []+ });+ let bytes = serde_json::to_vec(&bogus).unwrap();+ assert!(decode_index(&bytes).unwrap().is_none());+ }++ #[test]+ fn malformed_json_errors() {+ assert!(decode_index(b"not-json").is_err());+ }++ #[test]+ fn invalid_oid_errors() {+ let bogus = serde_json::json!({+ "version": INDEX_FORMAT_VERSION,+ "parent_oid": "zzzz",+ "entries": []+ });+ let bytes = serde_json::to_vec(&bogus).unwrap();+ assert!(decode_index(&bytes).is_err());+ }+}diff --git a/crates/ragfs/src/git/mod.rs b/crates/ragfs/src/git/mod.rsnew file mode 100644index 000000000..e127f8456--- /dev/null+++ b/crates/ragfs/src/git/mod.rs@@ -0,0 +1,58 @@+//! Git version control module+//!+//! This module provides Git-based version control capabilities for OpenViking,+//! allowing users to commit snapshots, checkout previous versions, and view+//! history.+//!+//! Architecture+//!+//! - [`object_store`]: Trait and implementations for content-addressable storage+//! - [`ref_store`]: Trait and implementations for named reference storage+//! - [`backends`]: Backend implementations (local filesystem, S3)+//!+//! Example+//!+//! ```rust,ignore+//! use ragfs::git::backends::local::{LocalObjectStore, LocalRefStore};+//! use ragfs::git::object_store::ObjectStore;+//! use ragfs::git::ref_store::RefStore;+//!+//! # #[tokio::main]+//! # async fn main() {+//! let object_store = LocalObjectStore::new("/data/git");+//! let ref_store = LocalRefStore::new("/data/git");+//!+//! // Use object_store and ref_store...+//! # }+//! ```++pub mod backends;+pub mod commit;+pub mod config;+pub mod enumerate;+pub mod error;+pub mod index_store;+pub mod object_store;+pub mod ref_store;+pub mod service;+pub mod tree_builder;+pub mod types;+pub mod util;++pub use config::{GitConfig, GitLocalConfig, GitS3ConfigPy, GitTuningConfig};+pub use error::{GitError, ObjectStoreError, RefStoreError};+pub use index_store::{CommitIndex, IndexStore, IndexStoreError};+pub use object_store::ObjectStore;+pub use ref_store::RefStore;+pub use service::GitService;+pub use tree_builder::{flatten, lookup, TreeEditor};+pub use types::{+ Actor, CommitRequest, CommitResponse, IndexEntry, RestoreDiff, RestoreRequest,+ RestoreResponse, RestoreWritebackPartial, ShowRequest, ShowResponse,+};++// Re-exports from backends+pub use backends::local::{LocalIndexStore, LocalObjectStore, LocalRefStore};++#[cfg(feature = "s3")]+pub use backends::s3::{CasMode, S3Config, S3IndexStore, S3ObjectStore, S3RefStore};diff --git a/crates/ragfs/src/git/object_store.rs b/crates/ragfs/src/git/object_store.rsnew file mode 100644index 000000000..abdbfddc3--- /dev/null+++ b/crates/ragfs/src/git/object_store.rs@@ -0,0 +1,44 @@+//! ObjectStore trait - content-addressable storage for Git objects++use async_trait::async_trait;+use bytes::Bytes;+use gix_hash::ObjectId;++use crate::git::error::ObjectStoreError;++/// Content-addressable storage for Git objects.+///+/// This trait abstracts over storage backends (local filesystem, S3, etc.)+/// for storing and retrieving Git objects (blobs, trees, commits).+///+/// All operations are content-addressable by ObjectId (SHA-1).+/// `put` operations are idempotent - writing the same object multiple times+/// has the same effect as writing it once.+#[async_trait]+pub trait ObjectStore: Send + Sync + 'static {+ /// Write a zlib-compressed loose object.+ ///+ /// The `zlib_body` must be a valid zlib-compressed Git loose object,+ /// and `oid` must be the SHA-1 hash of the uncompressed object+ /// (including the Git header: "type size\0content").+ ///+ /// Implementations should ensure this is idempotent: calling `put`+ /// multiple times with the same `oid` is safe and has no additional effect.+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: Bytes,+ ) -> Result<(), ObjectStoreError>;++ /// Read and decompress an object.+ ///+ /// Returns the full uncompressed bytes (including Git header: "type size\0content").+ async fn get(&self, account: &str, oid: &ObjectId) -> Result<Bytes, ObjectStoreError>;++ /// Check if an object exists without reading its content.+ ///+ /// This is an optimization path - implementations should use the cheapest+ /// available method (e.g., `stat` for local, `HEAD` for S3).+ async fn exists(&self, account: &str, oid: &ObjectId) -> Result<bool, ObjectStoreError>;+}diff --git a/crates/ragfs/src/git/ref_store.rs b/crates/ragfs/src/git/ref_store.rsnew file mode 100644index 000000000..5643240f1--- /dev/null+++ b/crates/ragfs/src/git/ref_store.rs@@ -0,0 +1,41 @@+//! RefStore trait - named references to Git objects++use async_trait::async_trait;+use gix_hash::ObjectId;++use crate::git::error::RefStoreError;++/// Storage for named references (branches, tags) pointing to Git objects.+///+/// The core operation is `cas_update` (Compare-And-Swap), which ensures+/// atomicity and consistency in the presence of concurrent writers.+#[async_trait]+pub trait RefStore: Send + Sync + 'static {+ /// Read the current value of a ref.+ ///+ /// Returns `NotFound` if the ref doesn't exist.+ async fn read(&self, account: &str, ref_name: &str) -> Result<ObjectId, RefStoreError>;++ /// Compare-And-Swap update: write `new` only if current value == `expected`.+ ///+ /// - `expected = None` means "write only if ref doesn't exist yet"+ /// - `expected = Some(oid)` means "write only if ref currently has this oid"+ ///+ /// Returns `Conflict` if the expectation fails.+ async fn cas_update(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<(), RefStoreError>;++ /// List all refs under a prefix (e.g., "refs/heads/").+ ///+ /// Returns a list of (full_ref_name, target_oid) pairs.+ async fn list(+ &self,+ account: &str,+ prefix: &str,+ ) -> Result<Vec<(String, ObjectId)>, RefStoreError>;+}diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsnew file mode 100644index 000000000..e0bfd29c3--- /dev/null+++ b/crates/ragfs/src/git/service.rs@@ -0,0 +1,5426 @@+//! `GitService` - high-level integration tying together object/ref stores,+//! VFS enumeration, tree building, and commit-object construction.+//!+//! See design §8.1 for the `commit()` algorithm. Fast Path 1 (persistent+//! stat cache `commit_index.bin`) is wired through an optional+//! `IndexStore`: when present and the cached snapshot's `parent_oid` matches+//! the current branch HEAD, files whose `(size, mtime_ns)` match the cached+//! entry skip the read+SHA-1 step and reuse the cached blob OID. Fast Path 3+//! (`exists()` dedup before blob write) is implemented in the slow path: after+//! a blob's oid is computed, an `exists()` precheck skips the zlib compression+//! and `put` when the object is already present. It is a pure performance+//! optimization (`write_object` is idempotent) and can be toggled off via+//! [`GitService::with_blob_exists_precheck`].++use std::collections::{HashMap, HashSet};+use std::sync::Arc;+use std::time::UNIX_EPOCH;++use gix_hash::ObjectId;+use tracing::warn;++use crate::core::filesystem::FileSystem;+use crate::core::types::FileInfo;+use crate::git::{+ error::{GitError, ObjectStoreError, RefStoreError},+ index_store::{CommitIndex, IndexStore},+ object_store::ObjectStore,+ ref_store::RefStore,+ types::{+ CommitRequest, CommitResponse, IndexEntry, RestoreRequest, RestoreResponse, ShowRequest,+ ShowResponse,+ },+};++/// `GitService` orchestrates the full commit pipeline against a `FileSystem`+/// (the working tree), an `ObjectStore`, and a `RefStore`. An optional+/// `IndexStore` enables Fast Path 1 — the persistent stat cache that lets+/// `commit()` skip read+SHA-1 for files whose `(size, mtime_ns)` are+/// unchanged since the last commit.+pub struct GitService {+ /// Working-tree filesystem rooted at `/local/{account}`.+ pub vfs: Arc<dyn FileSystem>,+ /// Backing object store (loose Git objects, content-addressed).+ pub object_store: Arc<dyn ObjectStore>,+ /// Backing ref store (branch heads).+ pub ref_store: Arc<dyn RefStore>,+ /// Optional Fast Path 1 stat cache. `None` disables the optimization+ /// — every commit then reads and SHA-1s every candidate file.+ pub index_store: Option<Arc<dyn IndexStore>>,+ /// Fast Path 3 toggle: when `true` (default), the slow path runs an+ /// `exists()` precheck before compressing and putting a blob. Disable to+ /// fall back to an unconditional `write_object`.+ pub blob_exists_precheck: bool,+}++impl GitService {+ /// Build a service without Fast Path 1. Equivalent to+ /// [`GitService::with_index`] passing `None`.+ pub fn new(+ vfs: Arc<dyn FileSystem>,+ object_store: Arc<dyn ObjectStore>,+ ref_store: Arc<dyn RefStore>,+ ) -> Self {+ Self {+ vfs,+ object_store,+ ref_store,+ index_store: None,+ blob_exists_precheck: true,+ }+ }++ /// Build a service with an optional [`IndexStore`] backing Fast Path 1.+ /// Pass `Some(...)` to enable the stat cache, `None` for parity with+ /// [`GitService::new`].+ pub fn with_index(+ vfs: Arc<dyn FileSystem>,+ object_store: Arc<dyn ObjectStore>,+ ref_store: Arc<dyn RefStore>,+ index_store: Option<Arc<dyn IndexStore>>,+ ) -> Self {+ Self {+ vfs,+ object_store,+ ref_store,+ index_store,+ blob_exists_precheck: true,+ }+ }++ /// Toggle Fast Path 3 (`exists()` precheck before blob write). Defaults to+ /// enabled; pass `false` to force an unconditional `write_object` on the+ /// slow path.+ pub fn with_blob_exists_precheck(mut self, enabled: bool) -> Self {+ self.blob_exists_precheck = enabled;+ self+ }++ /// Build a new commit on `branch` reflecting the current state of the+ /// account's VFS subtree.+ ///+ /// - If `paths` is `Some`, only those account-relative paths are+ /// considered (each is still pruned via `enumerate::prune_path`).+ /// - If `paths` is `None`, the full `/local/{account}` subtree is+ /// enumerated via `enumerate::collect_all`.+ ///+ /// On no-op (no editor change) the branch ref is untouched and+ /// `CommitResponse::Noop` is returned.+ ///+ /// When `paths` is `Some(...)`, every listed path must refer to a file in+ /// the VFS. To commit a subtree, list each file explicitly or omit `paths`+ /// for full enumeration.+ ///+ /// On a CAS conflict, returns `GitError::ConcurrentCommit` so the+ /// caller can decide whether to retry. There is intentionally no+ /// retry loop inside `commit()`.+ ///+ /// Fast Path 1: when an [`IndexStore`] is configured and the cached+ /// snapshot's `parent_oid` matches `prev_head`, candidates whose+ /// `(size, mtime_ns)` match the cached entry skip read+SHA-1 and reuse+ /// the cached blob OID. Any cache miss / parent mismatch / decode+ /// error silently falls back to the slow path; a stale or corrupt+ /// index can never produce an incorrect commit.+ pub async fn commit(&self, req: CommitRequest) -> Result<CommitResponse, GitError> {+ let CommitRequest {+ account,+ branch,+ message,+ paths,+ author_name,+ author_email,+ } = req;+ validate_account_id(&account)?;+ if let Some(ps) = &paths {+ for p in ps {+ validate_relative_path(p)?;+ }+ }+ let ref_name = format!("refs/heads/{branch}");++ // 1. Resolve current HEAD (may not exist → root commit).+ let prev_head: Option<ObjectId> = match self.ref_store.read(&account, &ref_name).await {+ Ok(oid) => Some(oid),+ Err(RefStoreError::NotFound(_)) => None,+ Err(e) => return Err(e.into()),+ };+ let prev_tree: Option<ObjectId> = match prev_head {+ Some(commit_oid) => Some(+ load_commit_meta(self.object_store.as_ref(), &account, &commit_oid)+ .await?+ .tree,+ ),+ None => None,+ };++ // 1b. Fast Path 1: load the persisted commit index for this branch+ // and verify its `parent_oid` matches `prev_head`. Any mismatch /+ // missing file / decode error → no cache for this commit.+ let prev_index: Option<CommitIndex> = match (&self.index_store, prev_head) {+ (Some(store), Some(head)) => match store.load(&account, &branch).await {+ Ok(Some(idx)) if idx.parent_oid == head => Some(idx),+ Ok(_) => None,+ Err(e) => {+ warn!(+ "commit index load failed for {account}/{branch}: {e}; \+ falling back to slow path"+ );+ None+ }+ },+ _ => None,+ };+ // Track whether Fast Path 1 is even potentially live: if disabled+ // (`index_store` is None), we skip the new-index build below.+ let fast_path_active = self.index_store.is_some() && prev_index.is_some();++ // 2. Build TreeEditor from prev tree if any; otherwise start empty.+ // (The well-known empty-tree oid is not guaranteed to exist in the+ // store, so we cannot blindly hand it to `from_tree`.)+ let mut editor = match prev_tree {+ Some(t) => {+ crate::git::tree_builder::TreeEditor::from_tree(+ self.object_store.as_ref(),+ &account,+ t,+ )+ .await?+ }+ None => crate::git::tree_builder::TreeEditor::empty(),+ };++ // 2.5. Explicit paths: classify each entry as File / Directory /+ // NotFound via a single VFS stat, and assemble three locals:+ //+ // * `candidates` - the deduped set of files this commit will+ // process. Directories contribute their recursive listing+ // (pruned) plus any prev_tree paths under the same prefix+ // (so deletions inside the directory surface as a remove).+ // A NotFound entry behaves the same way for any prev_tree+ // paths under its prefix, treating it as "delete whatever+ // used to live here".+ // * `cleanup_exact` - keys to drop from the new index seed+ // before the main loop re-fills them.+ // * `cleanup_prefixes` - directory-style prefixes ("docs/")+ // whose contents in the new index seed must also be dropped.+ //+ // Pruning is applied uniformly: explicit files, expanded+ // directory contents, and prev_tree-derived entries all run+ // through `prune_path`. A path supplied by the caller that is+ // pruned is silently dropped (no error, no warn).+ let mut cleanup_exact: HashSet<String> = HashSet::new();+ let mut cleanup_prefixes: Vec<String> = Vec::new();++ // Lazily flatten prev_tree once if any explicit path requires it.+ let mut prev_paths_cache: Option<Vec<(String, ObjectId)>> = None;++ let candidates: Vec<String> = match &paths {+ Some(ps) => {+ let mut set: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();++ for p in ps {+ let abs = format!("/local/{}/{}", account, p);+ match self.vfs.stat(&abs).await {+ Ok(info) if info.is_dir => {+ // Directory: recursive listing + prev_tree subtree.+ cleanup_prefixes.push(format!("{}/", p));++ let listed =+ crate::git::enumerate::collect_under(&self.vfs, &account, p)+ .await?;+ for rel in listed {+ set.insert(rel);+ }++ if let Some(t) = prev_tree {+ if prev_paths_cache.is_none() {+ prev_paths_cache = Some(+ crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ &account,+ t,+ &None,+ )+ .await?,+ );+ }+ let pref = format!("{}/", p);+ for (path, _) in prev_paths_cache.as_ref().unwrap() {+ if path.starts_with(&pref)+ && !crate::git::enumerate::prune_path(path)+ {+ set.insert(path.clone());+ }+ }+ }+ }+ Ok(_) => {+ // File: take it verbatim, subject to pruning.+ cleanup_exact.insert(p.clone());+ if !crate::git::enumerate::prune_path(p) {+ set.insert(p.clone());+ }+ }+ Err(e) if is_not_found(&e) => {+ // Neither file nor directory in the VFS. Treat+ // it as a delete-by-name: feed `p` into the main+ // loop (where the NotFound branch will remove it+ // from the tree if it was a file) AND union in+ // every prev_tree path under "p/" so a missing+ // directory drops its whole subtree.+ warn!(+ "commit path {:?} not found in VFS; \+ treating as deletion of any matching subtree",+ p+ );+ cleanup_exact.insert(p.clone());+ cleanup_prefixes.push(format!("{}/", p));++ if !crate::git::enumerate::prune_path(p) {+ set.insert(p.clone());+ }+ if let Some(t) = prev_tree {+ if prev_paths_cache.is_none() {+ prev_paths_cache = Some(+ crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ &account,+ t,+ &None,+ )+ .await?,+ );+ }+ let pref = format!("{}/", p);+ for (path, _) in prev_paths_cache.as_ref().unwrap() {+ if path.starts_with(&pref)+ && !crate::git::enumerate::prune_path(path)+ {+ set.insert(path.clone());+ }+ }+ }+ }+ Err(e) => return Err(e.into()),+ }+ }++ set.into_iter().collect()+ }+ // Full enumeration: union the files currently on disk with the+ // paths recorded in prev_tree. `collect_all` only sees files that+ // still exist, so a file deleted since the last commit would never+ // become a candidate and its deletion would be silently lost. By+ // adding prev_tree's paths, a path that's gone from disk falls into+ // the `NotFound → remove` branch below and is dropped from the new+ // snapshot. Deduped via BTreeSet so a path present in both sources+ // is only processed once.+ None => {+ let mut set: std::collections::BTreeSet<String> =+ crate::git::enumerate::collect_all(&self.vfs, &account)+ .await?+ .into_iter()+ .collect();+ if let Some(t) = prev_tree {+ let prev_paths = crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ &account,+ t,+ &None,+ )+ .await?;+ for (p, _) in prev_paths {+ if !crate::git::enumerate::prune_path(&p) {+ set.insert(p);+ }+ }+ }+ set.into_iter().collect()+ }+ };++ // 3b. Seed the new index. For partial commits (paths=Some), unlisted+ // paths in the previous index must be preserved verbatim — they+ // were not enumerated this round, so the cache should keep them.+ // For full enumeration (paths=None), start empty: only paths seen+ // this commit end up in the new index.+ let mut new_index_entries: HashMap<String, IndexEntry> =+ match (self.index_store.is_some(), &paths, &prev_index) {+ (true, Some(_), Some(idx)) => idx.entries.clone(),+ (true, _, _) => HashMap::new(),+ _ => HashMap::new(),+ };+ // For partial commits we still need to drop entries for any explicitly+ // listed path before we re-fill it — otherwise a deleted path that+ // was in the old index would linger. Directory entries clean by+ // prefix; file/NotFound entries clean by exact key.+ if paths.is_some() {+ for key in &cleanup_exact {+ new_index_entries.remove(key);+ }+ if !cleanup_prefixes.is_empty() {+ new_index_entries+ .retain(|k, _| !cleanup_prefixes.iter().any(|pref| k.starts_with(pref)));+ }+ }++ // 4. For each candidate: detect delete vs upsert. Blob writes on the+ // slow path go through Fast Path 3 (exists precheck) when enabled;+ // write_object is idempotent regardless.+ //+ // `prev_lookup_cache` memoises decoded prev_tree subtree contents+ // keyed on tree OID, so K candidate paths sharing the same depth-D+ // ancestor chain pay D unique loads instead of K×D — every commit+ // in the same parent subtree only fetches each ancestor once.+ // Pre-seeded with the editor's root entries so the first+ // `lookup_cached` doesn't re-fetch what `from_tree` already decoded.+ let mut prev_lookup_cache = crate::git::tree_builder::TreeLookupCache::new();+ if let Some(t) = prev_tree {+ prev_lookup_cache.seed(t, editor.root.clone());+ }+ // Racy-clean threshold: the time the loaded index was written (from the+ // backend's own metadata). A cached entry is only trustworthy when its+ // `mtime_ns` is strictly older than this — otherwise the file may have+ // been changed (to the same size) within the same clock tick as the+ // last commit, and `(size, mtime_ns)` cannot detect it. `None` (backend+ // could not report a write time) forces every entry down the slow path.+ let index_saved_at_ns: Option<i128> = prev_index.as_ref().and_then(|idx| idx.saved_at_ns);+ let mut changed = 0usize;+ for rel_path in candidates {+ let abs = format!("/local/{}/{}", account, rel_path);+ match self.vfs.stat(&abs).await {+ Ok(info) => {+ let stat = stat_signature(&info);++ // Fast Path 1: cached `(size, mtime_ns)` match → reuse oid,+ // skip vfs.read + write_object. The cached oid was once+ // written by a successful commit, so it's known good in+ // the object store. Guarded by the racy-clean check: the+ // entry's mtime must predate the index write, otherwise a+ // same-size change in the index's clock tick could slip+ // through undetected.+ let cached = prev_index+ .as_ref()+ .and_then(|idx| idx.entries.get(&rel_path));+ let oid = match (cached, stat) {+ (Some(entry), Some((size, mtime_ns)))+ if entry.size == size+ && entry.mtime_ns == mtime_ns+ && index_saved_at_ns.is_some_and(|saved| mtime_ns < saved) =>+ {+ entry.oid+ }+ _ => {+ let bytes = self.vfs.read(&abs, 0, 0).await?;+ if self.blob_exists_precheck {+ crate::git::util::write_object_if_absent(+ self.object_store.as_ref(),+ &account,+ gix_object::Kind::Blob,+ &bytes,+ )+ .await?+ } else {+ crate::git::util::write_object(+ self.object_store.as_ref(),+ &account,+ gix_object::Kind::Blob,+ &bytes,+ )+ .await?+ }+ }+ };++ // Skip the upsert if prev_tree already has this exact+ // path+oid — re-writing the same blob is not an editor+ // change and shouldn't count toward the no-op decision.+ let prev_entry = match prev_tree {+ Some(t) => {+ crate::git::tree_builder::lookup_cached(+ self.object_store.as_ref(),+ &account,+ t,+ &rel_path,+ &mut prev_lookup_cache,+ )+ .await?+ }+ None => None,+ };+ if prev_entry.map(|(o, _)| o) != Some(oid) {+ editor+ .upsert(self.object_store.as_ref(), &account, &rel_path, oid)+ .await?;+ changed += 1;+ }++ // Record in the new index regardless of whether the editor+ // was touched — the on-disk file is still present and+ // its (size, mtime_ns, oid) is the new ground truth.+ if self.index_store.is_some() {+ if let Some((size, mtime_ns)) = stat {+ new_index_entries.insert(+ rel_path.clone(),+ IndexEntry {+ size,+ mtime_ns,+ oid,+ },+ );+ } else {+ // No usable mtime → don't poison the cache.+ new_index_entries.remove(&rel_path);+ }+ }+ }+ Err(e) if is_not_found(&e) => {+ // Only count as a change if the path actually existed+ // in prev_tree, since TreeEditor::remove silently no-ops+ // for missing paths. With no prev_tree (root commit) a+ // missing path is just irrelevant.+ let prev_entry = match prev_tree {+ Some(t) => {+ crate::git::tree_builder::lookup_cached(+ self.object_store.as_ref(),+ &account,+ t,+ &rel_path,+ &mut prev_lookup_cache,+ )+ .await?+ }+ None => None,+ };+ if prev_entry.is_some() {+ editor+ .remove(self.object_store.as_ref(), &account, &rel_path)+ .await?;+ changed += 1;+ }+ // Path is gone → drop any lingering cache entry.+ if self.index_store.is_some() {+ new_index_entries.remove(&rel_path);+ }+ }+ Err(e) => return Err(e.into()),+ }+ }++ // 5. No-op short-circuit. Even though the tree didn't change, the+ // on-disk (size, mtime_ns) for enumerated paths may have shifted+ // (e.g. `touch` of an unchanged file). Persist the refreshed index+ // keyed on the *current* HEAD so the next commit can still hit the+ // fast path. Soft-fail on save errors.+ if changed == 0 {+ let noop_oid = prev_head.unwrap_or_else(|| ObjectId::null(gix_hash::Kind::Sha1));+ if let (Some(store), Some(parent)) = (&self.index_store, prev_head) {+ let new_index = CommitIndex {+ parent_oid: parent,+ entries: new_index_entries,+ // Stamped from the backing file's mtime on the next load.+ saved_at_ns: None,+ };+ if let Err(e) = store.save(&account, &branch, &new_index).await {+ warn!("commit index save failed for {account}/{branch}: {e}");+ }+ }+ let _ = fast_path_active;+ return Ok(CommitResponse::Noop {+ commit_oid: noop_oid,+ });+ }++ // 6. Write the new tree + the commit object.+ let new_tree = editor.write(self.object_store.as_ref(), &account).await?;+ let parents: Vec<ObjectId> = prev_head.iter().copied().collect();+ let commit_oid = crate::git::commit::write_commit(+ self.object_store.as_ref(),+ &account,+ new_tree,+ parents,+ &author_name,+ &author_email,+ &message,+ )+ .await?;++ // 7. CAS update the branch ref. Map Conflict → ConcurrentCommit.+ match self+ .ref_store+ .cas_update(&account, &ref_name, prev_head, commit_oid)+ .await+ {+ Ok(()) => {}+ Err(RefStoreError::Conflict { expected, actual }) => {+ return Err(GitError::ConcurrentCommit {+ ref_name,+ expected,+ actual,+ });+ }+ Err(other) => return Err(other.into()),+ }++ // 8. Persist the new commit index. Soft-fail: a save error logs and+ // continues — the commit itself has already succeeded; the worst+ // case is one slow-path commit next time.+ if let Some(store) = &self.index_store {+ let new_index = CommitIndex {+ parent_oid: commit_oid,+ entries: new_index_entries,+ // Stamped from the backing file's mtime on the next load.+ saved_at_ns: None,+ };+ if let Err(e) = store.save(&account, &branch, &new_index).await {+ warn!("commit index save failed for {account}/{branch}: {e}");+ }+ }+ // Suppress the "fast_path_active was set but never read" lint when no+ // future code path inspects it; left in scope for diagnostics.+ let _ = fast_path_active;++ Ok(CommitResponse::Created {+ commit_oid,+ changed,+ })+ }++ /// Read a commit's metadata, or a single blob's bytes from inside a commit's tree.+ ///+ /// `target_ref` resolution: 40-hex OID / "main" / "refs/heads/main".+ ///+ /// - `path = None` → returns `ShowResponse::Commit { oid, tree, parents, author, committer, message }`.+ /// - `path = Some(p)` → returns `ShowResponse::Blob { oid, size, bytes }` for the path inside+ /// the commit's tree. Missing path → `GitError::PathNotFound(p)`. Path that resolves to+ /// a tree (not a blob) → `GitError::PathIsDirectory(p)` — distinct from missing so callers+ /// can tell apart "no such path" from "path exists but is a directory, not a file".+ ///+ /// Missing ref → `GitError::RefStore(RefStoreError::NotFound)`.+ /// Missing commit object → `GitError::ObjectStore(ObjectStoreError::NotFound)`.+ pub async fn show(&self, req: ShowRequest) -> Result<ShowResponse, GitError> {+ let ShowRequest {+ account,+ target_ref,+ path,+ } = req;++ validate_account_id(&account)?;+ if let Some(p) = &path {+ validate_relative_path(p)?;+ }++ let commit_oid = resolve_ref(+ self.ref_store.as_ref(),+ self.object_store.as_ref(),+ &account,+ &target_ref,+ )+ .await?;+ let meta = load_commit_meta(self.object_store.as_ref(), &account, &commit_oid).await?;++ match path {+ None => Ok(ShowResponse::Commit {+ oid: commit_oid,+ tree: meta.tree,+ parents: meta.parents,+ author: meta.author,+ committer: meta.committer,+ message: meta.message,+ }),+ Some(p) => {+ let entry = crate::git::tree_builder::lookup(+ self.object_store.as_ref(),+ &account,+ meta.tree,+ &p,+ )+ .await?;+ let (blob_oid, mode) = entry.ok_or_else(|| GitError::PathNotFound(p.clone()))?;+ // Reject trees masquerading as paths: callers asked for blob bytes.+ if mode.is_tree() {+ return Err(GitError::PathIsDirectory(p));+ }+ let raw =+ crate::git::util::read_object(self.object_store.as_ref(), &account, &blob_oid)+ .await?;+ let (kind, payload_size, hdr) = crate::git::util::parse_object_header(&raw)?;+ if kind != gix_object::Kind::Blob {+ return Err(GitError::CorruptedObject(format!(+ "expected blob at {p}, got {kind:?}"+ )));+ }+ // `raw` is already a `Bytes`; `slice` is O(1) and shares the+ // backing buffer instead of allocating a fresh payload copy.+ let bytes = raw.slice(hdr..);+ Ok(ShowResponse::Blob {+ oid: blob_oid,+ size: payload_size,+ bytes,+ })+ }+ }+ }++ /// Restore a subtree at `project_dir` to the state it had in `source_commit`,+ /// producing a new commit whose parent is the **current HEAD** (not+ /// `source_commit`). HEAD always moves forward.+ ///+ /// See design §8.2 for the full algorithm and `RestoreResponse` for the+ /// three possible outcomes (`Applied` / `Noop` / `DryRun`).+ ///+ /// Errors:+ /// - `GitError::InvalidProjectDir` — `project_dir` is empty / malformed.+ /// - `GitError::RefStore(NotFound)` — branch HEAD or source_commit ref missing.+ /// - `GitError::SubtreeNotFoundInCommit` — `project_dir` does not resolve+ /// to a subtree in `source_commit`'s tree.+ /// - `GitError::ConcurrentCommit` — branch ref changed between our read+ /// and the CAS swap.+ pub async fn restore(&self, req: RestoreRequest) -> Result<RestoreResponse, GitError> {+ let RestoreRequest {+ account,+ branch,+ project_dir,+ source_commit,+ dry_run,+ message: _,+ author_name: _,+ author_email: _,+ } = &req;++ validate_account_id(account)?;++ if let Some(project_dir) = project_dir {+ validate_project_dir(project_dir)?;+ }+ let ref_name = format!("refs/heads/{branch}");++ // 1. Resolve both commits.+ let source_oid = resolve_ref(+ self.ref_store.as_ref(),+ self.object_store.as_ref(),+ account,+ source_commit,+ )+ .await?;+ let head_oid = self.ref_store.read(account, &ref_name).await?;+ let source_meta =+ load_commit_meta(self.object_store.as_ref(), account, &source_oid).await?;+ let head_meta = load_commit_meta(self.object_store.as_ref(), account, &head_oid).await?;++ // 2. Extract subtree from each (or use full tree if project_dir is None).+ // Source missing → error (if project_dir is Some).+ // Head missing → treat as empty (every file is a fresh write).+ let (source_tree_to_flatten, head_tree_to_flatten) = match project_dir {+ Some(project_dir) => {+ let source_subtree = match crate::git::tree_builder::lookup(+ self.object_store.as_ref(),+ account,+ source_meta.tree,+ project_dir,+ )+ .await?+ {+ Some((oid, mode)) if mode.is_tree() => oid,+ _ => {+ return Err(GitError::SubtreeNotFoundInCommit {+ project_dir: project_dir.clone(),+ commit: source_oid,+ });+ }+ };+ let head_subtree = match crate::git::tree_builder::lookup(+ self.object_store.as_ref(),+ account,+ head_meta.tree,+ project_dir,+ )+ .await?+ {+ Some((oid, mode)) if mode.is_tree() => Some(oid),+ _ => None,+ };+ (source_subtree, head_subtree)+ }+ None => (source_meta.tree, Some(head_meta.tree)),+ };++ // 3. Flatten and diff (paths in the result are subtree-relative, or account-relative if full tree).+ let source_entries = crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ account,+ source_tree_to_flatten,+ &None,+ )+ .await?;+ let head_entries = match head_tree_to_flatten {+ Some(oid) => {+ crate::git::tree_builder::flatten(self.object_store.as_ref(), account, oid, &None)+ .await?+ }+ None => Vec::new(),+ };+ let diff = compute_subtree_diff(&source_entries, &head_entries);++ // 4. dry_run short-circuits BEFORE any writes.+ if *dry_run {+ return Ok(RestoreResponse::DryRun {+ diff,+ head: head_oid,+ source: source_oid,+ });+ }++ // 5. Source == head → noop.+ if diff.to_write.is_empty() && diff.to_delete.is_empty() {+ return Ok(RestoreResponse::Noop {+ head: head_oid,+ source: source_oid,+ });+ }++ // 6. Prepare writeback metadata. Paths in the diff are relative to+ // project_dir — prefix here. NOTE: the VFS is NOT mutated yet. The+ // ref-consistency protocol (steps 7–9) must complete first so that a+ // losing CAS race leaves the working tree untouched; the actual+ // writeback happens in step 10 only after the ref swap succeeds.+ use futures::stream::{self, StreamExt};++ let abs_prefix = match project_dir {+ Some(project_dir) => format!("/local/{}/{}", account, project_dir),+ None => format!("/local/{}", account),+ };+ let unchanged_count = diff.unchanged.len();++ // 7. Build the new tree: load head.tree into an editor and splice+ // source_subtree at project_dir, or use source tree directly if full restore.+ let new_tree_oid = match project_dir {+ Some(project_dir) => {+ let mut editor = crate::git::tree_builder::TreeEditor::from_tree(+ self.object_store.as_ref(),+ account,+ head_meta.tree,+ )+ .await?;+ editor+ .upsert_subtree(+ self.object_store.as_ref(),+ account,+ project_dir,+ source_tree_to_flatten,+ )+ .await?;+ editor.write(self.object_store.as_ref(), account).await?+ }+ None => source_meta.tree,+ };++ // 8. Construct the new commit. parent = head_oid (NOT source_oid).+ let msg = req.message.clone().unwrap_or_else(|| {+ let short = &source_oid.to_hex().to_string()[..12.min(40)];+ match &req.project_dir {+ Some(project_dir) => format!("restore {} from {}", project_dir, short),+ None => format!("restore full tree from {}", short),+ }+ });+ let new_commit_oid = crate::git::commit::write_commit(+ self.object_store.as_ref(),+ account,+ new_tree_oid,+ vec![head_oid],+ &req.author_name,+ &req.author_email,+ &msg,+ )+ .await?;++ // 9. CAS-swap the branch ref. Map Conflict → ConcurrentCommit.+ // This MUST happen before any VFS writeback: if another commit+ // advanced the branch between our HEAD read and now, the CAS fails+ // and we return early with the working tree still matching HEAD,+ // leaving caller-driven reindex and on-disk state consistent.+ match self+ .ref_store+ .cas_update(account, &ref_name, Some(head_oid), new_commit_oid)+ .await+ {+ Ok(()) => {}+ Err(crate::git::error::RefStoreError::Conflict { expected, actual }) => {+ return Err(GitError::ConcurrentCommit {+ ref_name,+ expected,+ actual,+ });+ }+ Err(other) => return Err(other.into()),+ }++ // 10. The ref swap committed our new state. Now write back through the+ // VFS so the working tree reflects the restored content. The ref+ // has already advanced, so a per-path failure here can NOT be+ // rolled back — instead the streams below collect every failure+ // and we surface them as `GitError::RestoreWritebackPartial`. The+ // caller (Python) then schedules reindex for the paths that *did*+ // reach the VFS so the vector index does not stay stale.+ let object_store_ref = self.object_store.clone();+ let vfs_ref = self.vfs.clone();+ let account_owned = account.clone();+ let abs_prefix_for_writes = abs_prefix.clone();+ let project_dir_for_writes = project_dir.clone();++ let write_results: Vec<(String, Result<(), GitError>)> =+ stream::iter(diff.to_write.clone().into_iter())+ .map(|(rel, blob_oid)| {+ let object_store = object_store_ref.clone();+ let vfs = vfs_ref.clone();+ let account = account_owned.clone();+ let abs_prefix = abs_prefix_for_writes.clone();+ let project_dir = project_dir_for_writes.clone();+ async move {+ let account_rel = match &project_dir {+ Some(pd) => format!("{}/{}", pd, rel),+ None => rel.clone(),+ };+ let r = async {+ let bytes =+ read_blob_payload(object_store.as_ref(), &account, &blob_oid)+ .await?;+ let abs = format!("{}/{}", abs_prefix, rel);+ // The target's parent directory may have been removed out of+ // band (e.g. an `rm -r` that a later commit recorded as a+ // deletion), so the restore must recreate the directory+ // chain before writing the blob back.+ crate::core::filesystem::FileSystem::ensure_parent_dirs(+ vfs.as_ref(),+ &abs,+ 0o755,+ )+ .await?;+ crate::core::filesystem::FileSystem::write(+ vfs.as_ref(),+ &abs,+ &bytes,+ 0,+ crate::core::types::WriteFlag::Create,+ )+ .await?;+ Ok::<(), GitError>(())+ }+ .await;+ (account_rel, r)+ }+ })+ .buffer_unordered(32)+ .collect()+ .await;++ let abs_prefix_for_deletes = abs_prefix.clone();+ let vfs_for_deletes = self.vfs.clone();+ let project_dir_for_deletes = project_dir.clone();+ let delete_results: Vec<(String, Result<(), GitError>)> =+ stream::iter(diff.to_delete.clone().into_iter())+ .map(|rel| {+ let vfs = vfs_for_deletes.clone();+ let abs_prefix = abs_prefix_for_deletes.clone();+ let project_dir = project_dir_for_deletes.clone();+ async move {+ let account_rel = match &project_dir {+ Some(pd) => format!("{}/{}", pd, rel),+ None => rel.clone(),+ };+ let abs = format!("{}/{}", abs_prefix, rel);+ // Restore is idempotent: a path the diff wants to delete may+ // already be absent from the VFS (e.g. derived files like+ // `.abstract.md` that were removed or regenerated out of band).+ // Treat NotFound as success rather than counting it as a failure.+ let r =+ match crate::core::filesystem::FileSystem::remove(vfs.as_ref(), &abs)+ .await+ {+ Ok(_) => Ok::<(), GitError>(()),+ Err(crate::core::errors::Error::NotFound(_)) => Ok(()),+ Err(e) => Err(e.into()),+ };+ (account_rel, r)+ }+ })+ .buffer_unordered(32)+ .collect()+ .await;++ // 10b. Prune directories left empty by the deletes above. Git does not+ // track directories, so `to_delete` only ever lists files; removing+ // the last file in a directory would otherwise leave an empty husk+ // in the VFS. Walk each deleted file's ancestor directories (within+ // project_dir, deepest first) and drop any that are now empty.+ // Best-effort: a directory that still holds entries, or has already+ // vanished, is simply skipped — pruning never aborts the restore.+ use std::collections::BTreeSet;+ // (depth, rel_dir): BTreeSet iterates ascending, so reversing yields the+ // deepest directories first — children are pruned before their parents,+ // letting a parent that held only pruned subdirs be removed in turn.+ let mut prune_candidates: BTreeSet<(usize, String)> = BTreeSet::new();+ for rel in &diff.to_delete {+ let mut dir = rel.as_str();+ while let Some(idx) = dir.rfind('/') {+ dir = &dir[..idx];+ prune_candidates.insert((dir.split('/').count(), dir.to_string()));+ }+ }+ for (_depth, rel_dir) in prune_candidates.into_iter().rev() {+ let abs = format!("{}/{}", abs_prefix, rel_dir);+ let is_empty = match crate::core::filesystem::FileSystem::read_dir(+ self.vfs.as_ref(),+ &abs,+ )+ .await+ {+ Ok(entries) => entries.is_empty(),+ // Missing or not a directory → nothing to prune.+ Err(_) => false,+ };+ if is_empty {+ // Ignore failures: a concurrent writer may have repopulated the+ // directory, or it may already be gone. Either way the restore+ // itself has succeeded.+ let _ = crate::core::filesystem::FileSystem::remove(self.vfs.as_ref(), &abs).await;+ }+ }++ // 10c. Partition the per-path results into success / failure buckets.+ // `written_paths` / `deleted_paths` here only carry the paths+ // that actually reached the VFS — callers use these lists to+ // drive reindex, and a path whose write failed must not be+ // reindexed (the file's blob never landed).+ let mut written_paths: Vec<String> = Vec::with_capacity(write_results.len());+ let mut failed_writes: Vec<(String, String)> = Vec::new();+ for (path, r) in write_results {+ match r {+ Ok(()) => written_paths.push(path),+ Err(e) => failed_writes.push((path, e.to_string())),+ }+ }+ let mut deleted_paths: Vec<String> = Vec::with_capacity(delete_results.len());+ let mut failed_deletes: Vec<(String, String)> = Vec::new();+ for (path, r) in delete_results {+ match r {+ Ok(()) => deleted_paths.push(path),+ Err(e) => failed_deletes.push((path, e.to_string())),+ }+ }++ let written_actual = written_paths.len();+ let deleted_actual = deleted_paths.len();++ // 11. Partial failure path. The ref has already advanced, so we+ // cannot rollback — surface a structured error carrying enough+ // payload for the caller to schedule reindex for the paths that+ // *did* succeed and to report the failures upward.+ if !failed_writes.is_empty() || !failed_deletes.is_empty() {+ return Err(GitError::RestoreWritebackPartial(Box::new(+ crate::git::types::RestoreWritebackPartial {+ new_commit_oid,+ source_commit: source_oid,+ parent_commit: head_oid,+ written: written_actual,+ deleted: deleted_actual,+ unchanged: unchanged_count,+ written_paths,+ deleted_paths,+ failed_writes,+ failed_deletes,+ },+ )));+ }++ Ok(RestoreResponse::Applied {+ new_commit_oid,+ source_commit: source_oid,+ parent_commit: head_oid,+ written: written_actual,+ deleted: deleted_actual,+ unchanged: unchanged_count,+ written_paths,+ deleted_paths,+ })+ }+}++/// Load a blob object and return only its payload bytes (header stripped).+///+/// Errors out with `CorruptedObject` if the loaded object is not a blob —+/// this should not happen on a well-formed store but is cheap to verify.+async fn read_blob_payload(+ store: &dyn ObjectStore,+ account: &str,+ blob_oid: &gix_hash::ObjectId,+) -> Result<bytes::Bytes, GitError> {+ let raw = crate::git::util::read_object(store, account, blob_oid).await?;+ let (kind, _, hdr) = crate::git::util::parse_object_header(&raw)?;+ if kind != gix_object::Kind::Blob {+ return Err(GitError::CorruptedObject(format!(+ "expected blob, got {kind:?}"+ )));+ }+ Ok(raw.slice(hdr..))+}++/// Resolve `target_ref` to a commit OID.+///+/// Accepts:+/// 1. 40-hex commit OID (validated by `ObjectId::from_hex`)+/// 2. Abbreviated OID (4–39 hex chars) — resolved by listing refs and+/// walking parent chains; returns `OidPrefixNotFound` or `AmbiguousOid`+/// on zero / multiple matches+/// 3. Full ref path beginning with `refs/` (passed through `validate_ref_name`,+/// then read from `ref_store`)+/// 4. Short branch name (e.g. "main") — auto-prefixed to `refs/heads/{name}`,+/// validated, then read from `ref_store`+///+/// Returns `RefStoreError::NotFound` (wrapped) if the ref doesn't exist;+/// `GitError::Other` if `target_ref` is neither a valid OID nor a valid ref name.+///+/// Note: a 40-char hex string is always interpreted as an OID, even if it+/// happens to also be a valid branch name (e.g. `deadbeefdeadbeef...`).+/// To disambiguate such a branch, pass the full ref path `refs/heads/<name>`.+async fn resolve_ref(+ ref_store: &dyn RefStore,+ object_store: &dyn ObjectStore,+ account: &str,+ target_ref: &str,+) -> Result<ObjectId, GitError> {+ // 1. 40-hex commit OID — ASCII hex (case-insensitive), exactly len 40.+ if target_ref.len() == 40 && target_ref.bytes().all(|b| b.is_ascii_hexdigit()) {+ return ObjectId::from_hex(target_ref.as_bytes())+ .map_err(|e| GitError::Other(format!("invalid oid {target_ref}: {e}")));+ }++ // 2. Abbreviated OID (4–39 hex chars) — list refs and walk parent chains.+ if target_ref.len() >= 4 && target_ref.bytes().all(|b| b.is_ascii_hexdigit()) {+ return resolve_abbreviated_oid(ref_store, object_store, account, target_ref).await;+ }++ // 3 & 4. Normalize to full ref path then read.+ let full = if target_ref.starts_with("refs/") {+ target_ref.to_string()+ } else {+ format!("refs/heads/{target_ref}")+ };+ crate::git::util::validate_ref_name(&full)?;+ Ok(ref_store.read(account, &full).await?)+}++/// Decoded commit metadata used by `commit()` (just the tree) and `show()`+/// (full set). Owned so callers don't have to juggle the raw buffer.+struct CommitMeta {+ tree: ObjectId,+ parents: Vec<ObjectId>,+ author: crate::git::types::Actor,+ committer: crate::git::types::Actor,+ message: String,+}++/// Read a commit object and return its decoded metadata.+async fn load_commit_meta(+ store: &dyn ObjectStore,+ account: &str,+ commit_oid: &ObjectId,+) -> Result<CommitMeta, GitError> {+ let raw = crate::git::util::read_object(store, account, commit_oid).await?;+ let (kind, _, hdr) = crate::git::util::parse_object_header(&raw)?;+ if kind != gix_object::Kind::Commit {+ return Err(GitError::Other(format!(+ "expected commit object, got {kind:?}"+ )));+ }+ let parsed = gix_object::CommitRef::from_bytes(&raw[hdr..])+ .map_err(|e| GitError::Other(format!("commit decode: {e}")))?;+ Ok(CommitMeta {+ tree: parsed.tree(),+ parents: parsed.parents().collect(),+ author: actor_from_signature_ref(&parsed.author),+ committer: actor_from_signature_ref(&parsed.committer),+ message: parsed.message.to_string(),+ })+}++/// Resolve an abbreviated commit OID (4–39 hex chars) by walking the parent+/// chains from every ref tip in the account. The traversal is bounded by+/// `MAX_OID_RESOLVE_VISITED` to keep degenerate histories from running away.+///+/// Returns:+/// - `Ok(oid)` if exactly one commit's hex starts with `prefix`.+/// - `Err(GitError::OidPrefixNotFound)` if no commit matches.+/// - `Err(GitError::AmbiguousOid)` if 2+ commits match (lists up to 5 candidates).+///+/// Lowercases `prefix` before comparison; the input is already known to be+/// ASCII hex by the caller.+async fn resolve_abbreviated_oid(+ ref_store: &dyn RefStore,+ object_store: &dyn ObjectStore,+ account: &str,+ prefix: &str,+) -> Result<ObjectId, GitError> {+ use std::collections::HashSet;++ const MAX_OID_RESOLVE_VISITED: usize = 50_000;+ const MAX_REPORTED_CANDIDATES: usize = 5;++ let prefix_lc = prefix.to_ascii_lowercase();++ let refs = ref_store.list(account, "refs/").await?;+ let mut visited: HashSet<ObjectId> = HashSet::new();+ let mut queue: Vec<ObjectId> = refs.into_iter().map(|(_, oid)| oid).collect();+ let mut matches: Vec<ObjectId> = Vec::new();++ while let Some(oid) = queue.pop() {+ if !visited.insert(oid) {+ continue;+ }+ if visited.len() > MAX_OID_RESOLVE_VISITED {+ return Err(GitError::Other(format!(+ "OID prefix resolution aborted: scanned over {MAX_OID_RESOLVE_VISITED} commits without converging"+ )));+ }+ if oid.to_hex().to_string().starts_with(&prefix_lc) {+ matches.push(oid);+ if matches.len() > MAX_REPORTED_CANDIDATES {+ // Continue scanning a little longer to give a useful error,+ // but we already know it's ambiguous.+ break;+ }+ }+ let meta = match load_commit_meta(object_store, account, &oid).await {+ Ok(m) => m,+ Err(GitError::ObjectStore(ObjectStoreError::NotFound(_))) => continue,+ Err(GitError::Other(_)) => continue, // not a commit (tag etc.) — skip+ Err(e) => return Err(e),+ };+ for p in meta.parents {+ if !visited.contains(&p) {+ queue.push(p);+ }+ }+ }++ match matches.len() {+ 0 => Err(GitError::OidPrefixNotFound {+ prefix: prefix.to_string(),+ }),+ 1 => Ok(matches.into_iter().next().unwrap()),+ n => {+ let listed: Vec<String> = matches+ .iter()+ .take(MAX_REPORTED_CANDIDATES)+ .map(|o| o.to_hex().to_string())+ .collect();+ Err(GitError::AmbiguousOid {+ prefix: prefix.to_string(),+ count: n,+ candidates: listed.join(", "),+ })+ }+ }+}++/// Project a borrowed `gix_actor::SignatureRef` into our owned `Actor` DTO.+///+/// gix-actor 0.31.5 fields used: `SignatureRef.name: &BStr`, `.email: &BStr`,+/// `.time: gix_date::Time` (not the raw `&str` of later versions). `Time`+/// provides `.seconds: i64` and `.offset: i32`.+// TODO: gix_date::Time.sign dropped — Actor not roundtrip-safe for "-0000"+fn actor_from_signature_ref(sig: &gix_actor::SignatureRef<'_>) -> crate::git::types::Actor {+ crate::git::types::Actor {+ name: sig.name.to_string(),+ email: sig.email.to_string(),+ time_seconds: sig.time.seconds,+ tz_offset_seconds: sig.time.offset,+ }+}++/// Return true iff `e` is `Error::NotFound(_)`.+fn is_not_found(e: &crate::core::errors::Error) -> bool {+ matches!(e, crate::core::errors::Error::NotFound(_))+}++/// Project a `FileInfo` into the `(size, mtime_ns)` pair Fast Path 1 keys on.+///+/// Returns `None` when the file's `mod_time` is unrepresentable (pre-epoch+/// times wider than `i128` can hold are degenerate). A `None` here means the+/// path simply will not participate in Fast Path 1 — the slow path+/// (read+SHA-1) is taken and the cache entry is dropped, never poisoned.+fn stat_signature(info: &FileInfo) -> Option<(u64, i128)> {+ let dur = info.mod_time.duration_since(UNIX_EPOCH).ok()?;+ let nanos: i128 = dur.as_nanos() as i128;+ Some((info.size, nanos))+}++/// Validate an `account` id before it is used to build any filesystem path+/// (local backend) or S3 key prefix. This is the Rust-side equivalent of the+/// Python `validate_account_id` and is the single choke point that keeps a+/// crafted account (e.g. `../x`, `a/b`, `a\b`) from escaping its per-account+/// directory / key prefix when a binding is called directly.+///+/// Rules (mirroring `openviking/core/identifiers.py`):+/// - non-empty+/// - not `.` or `..`+/// - only `[A-Za-z0-9_.@-]` (rejects `/`, `\`, whitespace, control chars, …)+/// - at most one `@`+/// - must not start with `_`+fn validate_account_id(account: &str) -> Result<(), GitError> {+ if account.is_empty() {+ return Err(GitError::InvalidAccountId("account_id is empty".into()));+ }+ if account == "." || account == ".." {+ return Err(GitError::InvalidAccountId(+ "account_id must not be '.' or '..'".into(),+ ));+ }+ if !account+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'.' | b'@' | b'-'))+ {+ return Err(GitError::InvalidAccountId(format!(+ "account_id must be an alphanumeric string: {account:?}"+ )));+ }+ if account.bytes().filter(|&b| b == b'@').count() > 1 {+ return Err(GitError::InvalidAccountId(+ "account_id must have at most one @".into(),+ ));+ }+ if account.starts_with('_') {+ return Err(GitError::InvalidAccountId(+ "account_id cannot start with underscore _".into(),+ ));+ }+ Ok(())+}++/// Validate `project_dir` matches the rules of `TreeEditor::upsert`:+/// non-empty, no leading/trailing `/`, no empty components, no `.` / `..`+/// segments, no backslash, no control characters. The traversal-related+/// rules guard the same boundary as `validate_account_id`: a direct PyO3+/// caller could otherwise pass `project_dir="../other"` and have the+/// service splice or restore *outside* the account's tree once the path is+/// concatenated into `/local/{account}/{project_dir}/...`.+fn validate_project_dir(project_dir: &str) -> Result<(), GitError> {+ if project_dir.is_empty() {+ return Err(GitError::InvalidProjectDir(+ "project_dir must be non-empty".into(),+ ));+ }+ if project_dir.starts_with('/') || project_dir.ends_with('/') {+ return Err(GitError::InvalidProjectDir(format!(+ "project_dir must not start or end with '/': {project_dir:?}"+ )));+ }+ for c in project_dir.split('/') {+ if c.is_empty() {+ return Err(GitError::InvalidProjectDir(format!(+ "project_dir contains empty segment: {project_dir:?}"+ )));+ }+ if c == "." || c == ".." {+ return Err(GitError::InvalidProjectDir(format!(+ "project_dir contains '.' or '..' segment: {project_dir:?}"+ )));+ }+ }+ if project_dir.contains('\\') {+ return Err(GitError::InvalidProjectDir(format!(+ "project_dir must not contain backslash: {project_dir:?}"+ )));+ }+ if project_dir.bytes().any(|b| b < 0x20 || b == 0x7f) {+ return Err(GitError::InvalidProjectDir(format!(+ "project_dir contains control character: {project_dir:?}"+ )));+ }+ Ok(())+}++/// Validate a user-supplied relative path that will be concatenated with+/// `/local/{account}/` (commit) or looked up in a Git tree (show). Same+/// reasoning as `validate_account_id` / `validate_project_dir`: the Rust+/// GitService is a native boundary, so it must defend against `..` /+/// backslash / control chars itself rather than trust the caller (PyO3+/// binding, future SDK consumer) to have normalized first.+///+/// Rules: non-empty; no leading/trailing `/`; no empty, `.`, or `..`+/// segment; no backslash; no control character.+fn validate_relative_path(path: &str) -> Result<(), GitError> {+ if path.is_empty() {+ return Err(GitError::InvalidPath("path must be non-empty".into()));+ }+ if path.starts_with('/') || path.ends_with('/') {+ return Err(GitError::InvalidPath(format!(+ "path must not start or end with '/': {path:?}"+ )));+ }+ for c in path.split('/') {+ if c.is_empty() {+ return Err(GitError::InvalidPath(format!(+ "path contains empty segment: {path:?}"+ )));+ }+ if c == "." || c == ".." {+ return Err(GitError::InvalidPath(format!(+ "path contains '.' or '..' segment: {path:?}"+ )));+ }+ }+ if path.contains('\\') {+ return Err(GitError::InvalidPath(format!(+ "path must not contain backslash: {path:?}"+ )));+ }+ if path.bytes().any(|b| b < 0x20 || b == 0x7f) {+ return Err(GitError::InvalidPath(format!(+ "path contains control character: {path:?}"+ )));+ }+ Ok(())+}++/// Pure-function diff between two flattened subtrees.+///+/// Both inputs are `(path, oid)` slices as returned by `tree_builder::flatten`+/// on a subtree OID — meaning the paths are already relative to the subtree+/// root (no `project_dir` prefix). Results are sorted by path.+fn compute_subtree_diff(+ source: &[(String, gix_hash::ObjectId)],+ head: &[(String, gix_hash::ObjectId)],+) -> crate::git::types::RestoreDiff {+ use std::collections::HashMap;+ let head_map: HashMap<&str, &gix_hash::ObjectId> =+ head.iter().map(|(p, o)| (p.as_str(), o)).collect();+ let source_map: HashMap<&str, &gix_hash::ObjectId> =+ source.iter().map(|(p, o)| (p.as_str(), o)).collect();++ let mut to_write = Vec::new();+ let mut unchanged = Vec::new();+ for (path, oid) in source {+ match head_map.get(path.as_str()) {+ Some(head_oid) if *head_oid == oid => unchanged.push(path.clone()),+ _ => to_write.push((path.clone(), *oid)),+ }+ }+ let mut to_delete: Vec<String> = head+ .iter()+ .filter(|(p, _)| !source_map.contains_key(p.as_str()))+ .map(|(p, _)| p.clone())+ .collect();++ to_write.sort_by(|a, b| a.0.cmp(&b.0));+ to_delete.sort();+ unchanged.sort();+ crate::git::types::RestoreDiff {+ to_write,+ to_delete,+ unchanged,+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use async_trait::async_trait;+ use std::collections::{HashMap, HashSet};+ use std::sync::{Arc, Mutex};++ use crate::core::errors::{Error, Result};+ use crate::core::filesystem::FileSystem;+ use crate::core::types::{FileInfo, TreeEntry, WriteFlag};+ use crate::git::backends::local::{LocalObjectStore, LocalRefStore};+ use crate::git::error::ObjectStoreError;+ use crate::git::error::RefStoreError;+ use crate::git::tree_builder::{flatten, lookup};++ /// In-memory VFS mock that owns a map from absolute path to bytes.+ /// Root for the account is always `/local/{account}` — paths inserted+ /// must be the absolute path including this prefix.+ struct MockVfs {+ account: String,+ files: Arc<Mutex<HashMap<String, Vec<u8>>>>,+ /// When true, `remove` returns NotFound for absent paths (like the real+ /// VFS) instead of silently succeeding. Used to exercise the idempotent+ /// delete path in restore.+ strict_remove: bool,+ /// Absolute paths whose `write` call should fail with an I/O error.+ /// Used by restore-partial tests to force a per-path writeback failure+ /// without otherwise breaking the mock VFS.+ fail_writes: Arc<Mutex<HashSet<String>>>,+ /// Absolute paths whose `remove` call should fail with an I/O error+ /// (NotFound-style errors are still produced by the existing+ /// `strict_remove` flag, not via this set — that mirrors the real+ /// "idempotent delete" semantics in service.rs).+ fail_removes: Arc<Mutex<HashSet<String>>>,+ }++ impl MockVfs {+ fn new(account: &str) -> Arc<Self> {+ Arc::new(Self {+ account: account.to_string(),+ files: Arc::new(Mutex::new(HashMap::new())),+ strict_remove: false,+ fail_writes: Arc::new(Mutex::new(HashSet::new())),+ fail_removes: Arc::new(Mutex::new(HashSet::new())),+ })+ }++ fn new_strict_remove(account: &str) -> Arc<Self> {+ Arc::new(Self {+ account: account.to_string(),+ files: Arc::new(Mutex::new(HashMap::new())),+ strict_remove: true,+ fail_writes: Arc::new(Mutex::new(HashSet::new())),+ fail_removes: Arc::new(Mutex::new(HashSet::new())),+ })+ }++ /// Insert/update file content. `rel` is account-relative.+ fn put(&self, rel: &str, data: &[u8]) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.files.lock().unwrap().insert(abs, data.to_vec());+ }++ /// Delete a file by account-relative path.+ fn delete(&self, rel: &str) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.files.lock().unwrap().remove(&abs);+ }++ /// Cause subsequent `write` calls targeting `rel` (account-relative)+ /// to return an I/O error.+ fn fail_write(&self, rel: &str) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.fail_writes.lock().unwrap().insert(abs);+ }++ /// Cause subsequent `remove` calls targeting `rel` (account-relative)+ /// to return an I/O error.+ fn fail_remove(&self, rel: &str) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.fail_removes.lock().unwrap().insert(abs);+ }+ }++ #[async_trait]+ impl FileSystem for MockVfs {+ async fn create(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn mkdir(&self, _path: &str, _mode: u32) -> Result<()> {+ // Directories are implicit in this flat file map, so creating one is+ // a no-op. Defined (rather than unimplemented!) so the default+ // `ensure_parent_dirs` used by restore's writeback succeeds.+ Ok(())+ }+ async fn remove(&self, path: &str) -> Result<()> {+ if self.fail_removes.lock().unwrap().contains(path) {+ return Err(Error::Internal(format!("forced remove failure: {path}")));+ }+ let existed = self.files.lock().unwrap().remove(path).is_some();+ if self.strict_remove && !existed {+ return Err(Error::not_found(path));+ }+ Ok(())+ }+ async fn remove_all(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }++ async fn read(&self, path: &str, _offset: u64, _size: u64) -> Result<Vec<u8>> {+ let g = self.files.lock().unwrap();+ match g.get(path) {+ Some(bytes) => Ok(bytes.clone()),+ None => Err(Error::not_found(path)),+ }+ }++ async fn write(+ &self,+ path: &str,+ data: &[u8],+ _offset: u64,+ _flags: WriteFlag,+ ) -> Result<u64> {+ if self.fail_writes.lock().unwrap().contains(path) {+ return Err(Error::Internal(format!("forced write failure: {path}")));+ }+ self.files+ .lock()+ .unwrap()+ .insert(path.to_string(), data.to_vec());+ Ok(data.len() as u64)+ }+ async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ unimplemented!()+ }++ async fn stat(&self, path: &str) -> Result<FileInfo> {+ let g = self.files.lock().unwrap();+ if let Some(bytes) = g.get(path) {+ let name = path.rsplit('/').next().unwrap_or(path).to_string();+ return Ok(FileInfo::new_file(name, bytes.len() as u64, 0o644));+ }+ Err(Error::not_found(path))+ }++ async fn rename(&self, _old_path: &str, _new_path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn chmod(&self, _path: &str, _mode: u32) -> Result<()> {+ unimplemented!()+ }++ async fn tree_directory(+ &self,+ path: &str,+ _show_hidden: bool,+ _node_limit: Option<usize>,+ _level_limit: Option<usize>,+ ) -> Result<Vec<TreeEntry>> {+ let prefix = if path == "/" {+ "/".to_string()+ } else {+ format!("{}/", path)+ };+ let g = self.files.lock().unwrap();+ let mut out = Vec::new();+ for (full_path, _bytes) in g.iter() {+ if !full_path.starts_with(&prefix) {+ continue;+ }+ let rel = full_path+ .strip_prefix(&prefix)+ .unwrap_or(full_path)+ .to_string();+ let name = full_path+ .rsplit('/')+ .next()+ .unwrap_or(full_path)+ .to_string();+ let info = FileInfo::new_file(name, 0, 0o644);+ out.push(TreeEntry {+ path: full_path.clone(),+ rel_path: rel,+ info,+ extra: HashMap::new(),+ });+ }+ Ok(out)+ }+ }++ /// Helper: build a fresh GitService backed by a temp dir + a fresh+ /// in-memory VFS for the given account.+ fn make_service(+ account: &str,+ ) -> (+ tempfile::TempDir,+ Arc<MockVfs>,+ Arc<LocalObjectStore>,+ Arc<LocalRefStore>,+ GitService,+ ) {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new(account);+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store.clone() as Arc<dyn RefStore>,+ );+ (dir, vfs, object_store, ref_store, svc)+ }++ fn req(+ account: &str,+ branch: &str,+ message: &str,+ paths: Option<Vec<String>>,+ ) -> CommitRequest {+ CommitRequest {+ account: account.to_string(),+ branch: branch.to_string(),+ message: message.to_string(),+ paths,+ author_name: "tester".to_string(),+ author_email: "[email protected]".to_string(),+ }+ }++ /// Load a commit's parent OIDs from the object store.+ async fn commit_parents(+ store: &dyn ObjectStore,+ account: &str,+ commit_oid: ObjectId,+ ) -> Vec<ObjectId> {+ let raw = crate::git::util::read_object(store, account, &commit_oid)+ .await+ .unwrap();+ let (_, _, hdr) = crate::git::util::parse_object_header(&raw).unwrap();+ let parsed = gix_object::CommitRef::from_bytes(&raw[hdr..]).unwrap();+ parsed.parents().collect()+ }++ async fn commit_tree(store: &dyn ObjectStore, account: &str, commit_oid: ObjectId) -> ObjectId {+ load_commit_meta(store, account, &commit_oid)+ .await+ .unwrap()+ .tree+ }++ /// Make a commit and return its OID.+ async fn make_commit(svc: &GitService, account: &str, branch: &str, msg: &str) -> ObjectId {+ match svc.commit(req(account, branch, msg, None)).await.unwrap() {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ }+ }++ // ── 1 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_first_creates_root_commit() {+ let (_dir, vfs, object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");++ let resp = svc+ .commit(req("acct", "main", "first", None))+ .await+ .unwrap();++ match resp {+ CommitResponse::Created {+ commit_oid,+ changed,+ } => {+ assert!(changed >= 1, "should record at least one change");+ let parents = commit_parents(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ commit_oid,+ )+ .await;+ assert!(parents.is_empty(), "root commit must have no parents");+ let tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ commit_oid,+ )+ .await;+ assert_ne!(tree, ObjectId::empty_tree(gix_hash::Kind::Sha1));+ let head = ref_store.read("acct", "refs/heads/main").await.unwrap();+ assert_eq!(head, commit_oid);+ }+ other => panic!("expected Created, got {other:?}"),+ }+ }++ // ── 2 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_second_links_to_first() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let first = svc+ .commit(req("acct", "main", "first", None))+ .await+ .unwrap();+ let first_oid = match first {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ vfs.put("resources/a.md", b"world");+ let second = svc+ .commit(req("acct", "main", "second", None))+ .await+ .unwrap();+ let second_oid = match second {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let parents = commit_parents(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ second_oid,+ )+ .await;+ assert_eq!(parents, vec![first_oid]);+ }++ // ── 3 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_noop_when_nothing_changed() {+ let (_dir, vfs, _object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let first = svc+ .commit(req("acct", "main", "first", None))+ .await+ .unwrap();+ let first_oid = match first {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let second = svc.commit(req("acct", "main", "noop", None)).await.unwrap();+ match second {+ CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first_oid),+ other => panic!("expected Noop, got {other:?}"),+ }++ let head = ref_store.read("acct", "refs/heads/main").await.unwrap();+ assert_eq!(head, first_oid);+ }++ // ── 4 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_handles_deletes() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ vfs.put("resources/b.md", b"world");+ let _ = svc+ .commit(req("acct", "main", "first", None))+ .await+ .unwrap();++ vfs.delete("resources/a.md");+ let resp = svc+ .commit(req(+ "acct",+ "main",+ "delete-a",+ Some(vec!["resources/a.md".to_string()]),+ ))+ .await+ .unwrap();+ let second_oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ second_oid,+ )+ .await;+ let all = flatten(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ tree,+ &None,+ )+ .await+ .unwrap();+ let paths: Vec<String> = all.into_iter().map(|(p, _)| p).collect();+ assert_eq!(paths, vec!["resources/b.md".to_string()]);+ }++ /// Helper: list every blob path in a commit's tree, sorted.+ async fn commit_paths(+ store: &dyn ObjectStore,+ account: &str,+ commit_oid: ObjectId,+ ) -> Vec<String> {+ let tree = commit_tree(store, account, commit_oid).await;+ let all = flatten(store, account, tree, &None).await.unwrap();+ all.into_iter().map(|(p, _)| p).collect()+ }++ // ── 4b ─────────────────────────────────────────────────────────────+ /// Full enumeration (`paths=None`) must capture a deletion: a file gone+ /// from disk but present in prev_tree is dropped from the new snapshot.+ #[tokio::test]+ async fn test_full_commit_captures_delete() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ vfs.put("resources/b.md", b"world");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ vfs.delete("resources/a.md");+ let resp = svc+ .commit(req("acct", "main", "full-delete", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created {+ commit_oid,+ changed,+ } => {+ assert_eq!(changed, 1, "exactly one path (a.md) was removed");+ commit_oid+ }+ other => panic!("expected Created, got {other:?}"),+ };++ let paths = commit_paths(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ assert_eq!(paths, vec!["resources/b.md".to_string()]);+ }++ // ── 4c ─────────────────────────────────────────────────────────────+ /// Full enumeration must capture deletion of an entire subdirectory.+ #[tokio::test]+ async fn test_full_commit_captures_subdir_delete() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/keep.md", b"keep");+ vfs.put("resources/sub/a.md", b"a");+ vfs.put("resources/sub/b.md", b"b");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ vfs.delete("resources/sub/a.md");+ vfs.delete("resources/sub/b.md");+ let resp = svc+ .commit(req("acct", "main", "drop-sub", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created {+ commit_oid,+ changed,+ } => {+ assert_eq!(changed, 2, "both files under sub/ were removed");+ commit_oid+ }+ other => panic!("expected Created, got {other:?}"),+ };++ let paths = commit_paths(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ assert_eq!(paths, vec!["resources/keep.md".to_string()]);+ }++ // ── 4d ─────────────────────────────────────────────────────────────+ /// Full enumeration must handle a file→dir transition: `foo` was a file,+ /// now `foo/bar.md` is a directory entry. The stale blob is replaced.+ #[tokio::test]+ async fn test_full_commit_file_to_dir_transition() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("foo", b"i am a file");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ vfs.delete("foo");+ vfs.put("foo/bar.md", b"now a dir");+ let resp = svc+ .commit(req("acct", "main", "file-to-dir", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let paths = commit_paths(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ assert_eq!(paths, vec!["foo/bar.md".to_string()]);+ }++ // ── 4e ─────────────────────────────────────────────────────────────+ /// Full enumeration must handle a dir→file transition: `foo/bar.md` was a+ /// directory, now `foo` is a file. The stale subtree is dropped.+ #[tokio::test]+ async fn test_full_commit_dir_to_file_transition() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("foo/bar.md", b"i am in a dir");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ vfs.delete("foo/bar.md");+ vfs.put("foo", b"now a file");+ let resp = svc+ .commit(req("acct", "main", "dir-to-file", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let paths = commit_paths(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ assert_eq!(paths, vec!["foo".to_string()]);+ }++ // ── 4f ─────────────────────────────────────────────────────────────+ /// Multi-level dir→file: `foo/bar/baz.md` collapses to a file `foo`.+ #[tokio::test]+ async fn test_full_commit_dir_to_file_transition_multilevel() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("foo/bar/baz.md", b"deep");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ vfs.delete("foo/bar/baz.md");+ vfs.put("foo", b"now a file");+ let resp = svc+ .commit(req("acct", "main", "deep-collapse", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let paths = commit_paths(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ assert_eq!(paths, vec!["foo".to_string()]);+ }++ // ── 5 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_with_explicit_paths_skips_others() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"A");+ vfs.put("resources/b.md", b"B");+ vfs.put("resources/c.md", b"C");++ let resp = svc+ .commit(req(+ "acct",+ "main",+ "only-a",+ Some(vec!["resources/a.md".to_string()]),+ ))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let tree = commit_tree(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ let all = flatten(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ tree,+ &None,+ )+ .await+ .unwrap();+ let paths: Vec<String> = all.into_iter().map(|(p, _)| p).collect();+ assert_eq!(paths, vec!["resources/a.md".to_string()]);+ // Sanity-check the blob is reachable via lookup too.+ let found = lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ tree,+ "resources/a.md",+ )+ .await+ .unwrap();+ assert!(found.is_some());+ }++ // ── 6 ──────────────────────────────────────────────────────────────++ /// Wrapping RefStore that forces the next `cas_update` call to fail+ /// with `Conflict`, then delegates to the inner store afterwards.+ struct ConflictOnceRef {+ inner: Arc<LocalRefStore>,+ fired: Mutex<bool>,+ actual: Option<ObjectId>,+ }++ #[async_trait]+ impl RefStore for ConflictOnceRef {+ async fn read(+ &self,+ account: &str,+ ref_name: &str,+ ) -> std::result::Result<ObjectId, RefStoreError> {+ self.inner.read(account, ref_name).await+ }++ async fn cas_update(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> std::result::Result<(), RefStoreError> {+ let should_conflict = {+ let mut fired = self.fired.lock().unwrap();+ if !*fired {+ *fired = true;+ true+ } else {+ false+ }+ };+ if should_conflict {+ return Err(RefStoreError::Conflict {+ expected,+ actual: self.actual,+ });+ }+ self.inner+ .cas_update(account, ref_name, expected, new)+ .await+ }++ async fn list(+ &self,+ account: &str,+ prefix: &str,+ ) -> std::result::Result<Vec<(String, ObjectId)>, RefStoreError> {+ self.inner.list(account, prefix).await+ }+ }++ #[tokio::test]+ async fn test_commit_cas_conflict_surfaces_as_error() {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let inner_ref = Arc::new(LocalRefStore::new(dir.path()));+ let bogus = ObjectId::from_hex(b"deadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap();+ let ref_store = Arc::new(ConflictOnceRef {+ inner: inner_ref.clone(),+ fired: Mutex::new(false),+ actual: Some(bogus),+ });+ let vfs = MockVfs::new("acct");+ vfs.put("resources/a.md", b"hello");+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store.clone() as Arc<dyn RefStore>,+ );++ let result = svc.commit(req("acct", "main", "boom", None)).await;+ match result {+ Err(GitError::ConcurrentCommit {+ ref_name,+ expected,+ actual,+ }) => {+ assert_eq!(ref_name, "refs/heads/main");+ assert_eq!(expected, None);+ assert_eq!(actual, Some(bogus));+ }+ other => panic!("expected ConcurrentCommit, got {other:?}"),+ }+ }++ // ── 7 ──────────────────────────────────────────────────────────────+ // Verifies the incremental commit path reuses unchanged subtree OIDs:+ // modifying a file under `resources/` must NOT rewrite the `agent/`+ // subtree object — its OID must be byte-identical across commits.+ #[tokio::test]+ async fn test_commit_incremental_reuses_unchanged_subtree_oids() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ vfs.put("agent/b.py", b"print('hi')");++ let first = svc+ .commit(req("acct", "main", "first", None))+ .await+ .unwrap();+ let first_oid = match first {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };+ let first_tree =+ commit_tree(object_store.as_ref() as &dyn ObjectStore, "acct", first_oid).await;+ let agent_first = lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ first_tree,+ "agent",+ )+ .await+ .unwrap()+ .expect("agent subtree must exist after first commit");+ assert!(agent_first.1.is_tree(), "agent entry must be a tree");++ // Touch only resources/a.md.+ vfs.put("resources/a.md", b"world");+ let second = svc+ .commit(req("acct", "main", "second", None))+ .await+ .unwrap();+ let second_oid = match second {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };+ let second_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ second_oid,+ )+ .await;+ assert_ne!(+ first_tree, second_tree,+ "root tree must change because resources/a.md changed",+ );+ let agent_second = lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ second_tree,+ "agent",+ )+ .await+ .unwrap()+ .expect("agent subtree must still exist after second commit");++ assert_eq!(+ agent_first.0, agent_second.0,+ "unchanged agent/ subtree OID must be reused across commits",+ );+ }++ // ── 8 ──────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_commit_skips_pruned_paths() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ vfs.put("resources/x.faiss", b"FAISS");+ vfs.put("_system/lock", b"L");++ let resp = svc+ .commit(req("acct", "main", "filtered", None))+ .await+ .unwrap();+ let oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let tree = commit_tree(object_store.as_ref() as &dyn ObjectStore, "acct", oid).await;+ let all = flatten(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ tree,+ &None,+ )+ .await+ .unwrap();+ let paths: Vec<String> = all.into_iter().map(|(p, _)| p).collect();+ assert_eq!(paths, vec!["resources/a.md".to_string()]);+ }++ // ── commit: paths supports directories ──────────────────────────────+ /// A directory in `paths` is expanded to every file under it that+ /// survives pruning. Files under the directory that were in the+ /// previous tree but have since been deleted from the VFS must drop+ /// out of the new snapshot.+ ///+ /// Backed by `LocalFileSystem`: `MockVfs::stat` returns NotFound for+ /// any directory entry, which would route this test through Step 2.5's+ /// NotFound branch instead of the Directory branch. A real filesystem+ /// is the only fixture where `stat("/local/acct/docs")` returns+ /// `is_dir = true`.+ #[tokio::test]+ async fn test_commit_paths_expands_directory_and_drops_deleted_files() {+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));+ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct");+ std::fs::create_dir_all(acct_root.join("docs")).unwrap();+ std::fs::create_dir_all(acct_root.join("other")).unwrap();+ std::fs::write(acct_root.join("docs/a.md"), b"AA").unwrap();+ std::fs::write(acct_root.join("docs/b.md"), b"BB").unwrap();+ std::fs::write(acct_root.join("other/c.md"), b"CC").unwrap();+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());+ let svc = GitService::new(vfs, object_store.clone(), ref_store);++ let _ = make_commit(&svc, "acct", "main", "first").await;++ // Delete b.md from VFS, add d.md, leave a.md unchanged.+ std::fs::remove_file(acct_root.join("docs/b.md")).unwrap();+ std::fs::write(acct_root.join("docs/d.md"), b"DD").unwrap();++ let resp = svc+ .commit(req("acct", "main", "scoped", Some(vec!["docs".into()])))+ .await+ .unwrap();+ let commit_oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Verify the new tree through show():+ // docs/a.md still present, docs/b.md gone, docs/d.md present,+ // other/c.md untouched.+ let oid_hex = commit_oid.to_hex().to_string();+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex.clone(),+ path: Some("docs/a.md".into()),+ })+ .await,+ Ok(ShowResponse::Blob { .. })+ ));+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex.clone(),+ path: Some("docs/b.md".into()),+ })+ .await,+ Err(GitError::PathNotFound(_))+ ));+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex.clone(),+ path: Some("docs/d.md".into()),+ })+ .await,+ Ok(ShowResponse::Blob { .. })+ ));+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex,+ path: Some("other/c.md".into()),+ })+ .await,+ Ok(ShowResponse::Blob { .. })+ ));+ }++ /// If the directory passed in `paths` does not exist in the VFS at all,+ /// every file under that prefix in prev_tree is dropped from the new+ /// snapshot. A `warn!` is emitted but no error is returned.+ /// Uses MockVfs: the directory is "missing" so Step 2.5 sees NotFound.+ #[tokio::test]+ async fn test_commit_paths_notfound_directory_drops_subtree() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("docs/a.md", b"AA");+ vfs.put("docs/b.md", b"BB");+ vfs.put("other/c.md", b"CC");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ // Whole directory disappears.+ vfs.delete("docs/a.md");+ vfs.delete("docs/b.md");++ let resp = svc+ .commit(req("acct", "main", "drop dir", Some(vec!["docs".into()])))+ .await+ .unwrap();+ let commit_oid = match resp {+ CommitResponse::Created {+ commit_oid,+ changed,+ } => {+ assert_eq!(changed, 3, "three files removed from snapshot");+ commit_oid+ }+ other => panic!("expected Created, got {other:?}"),+ };++ let oid_hex = commit_oid.to_hex().to_string();+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex.clone(),+ path: Some("docs/a.md".into()),+ })+ .await,+ Err(GitError::PathNotFound(_))+ ));+ assert!(matches!(+ svc.show(ShowRequest {+ account: "acct".into(),+ target_ref: oid_hex,+ path: Some("other/c.md".into()),+ })+ .await,+ Ok(ShowResponse::Blob { .. })+ ));+ }++ /// Pruning applies to explicit directories: passing `_system` results+ /// in a Noop commit (the directory does not exist in the VFS, but even+ /// if it did, every entry under it would be pruned).+ #[tokio::test]+ async fn test_commit_paths_pruned_directory_is_noop() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"AA");+ let first = make_commit(&svc, "acct", "main", "first").await;++ let resp = svc+ .commit(req(+ "acct",+ "main",+ "pruned dir",+ Some(vec!["_system".into()]),+ ))+ .await+ .unwrap();+ match resp {+ CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first),+ other => panic!("expected Noop, got {other:?}"),+ }+ }++ /// Pruning applies to explicit files: passing a pruned file path is+ /// equivalent to passing nothing. Noop on top of an existing commit.+ #[tokio::test]+ async fn test_commit_paths_pruned_file_is_noop() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"AA");+ vfs.put("_system/lock", b"LL"); // pruned, never committed+ let first = make_commit(&svc, "acct", "main", "first").await;++ let resp = svc+ .commit(req(+ "acct",+ "main",+ "pruned file",+ Some(vec!["_system/lock".into()]),+ ))+ .await+ .unwrap();+ match resp {+ CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first),+ other => panic!("expected Noop, got {other:?}"),+ }+ }++ /// Mixing a file and a directory containing that file processes each+ /// candidate exactly once. The resulting commit must record exactly+ /// the directory's content, not double-process the listed file. Uses+ /// LocalFileSystem so the Directory branch actually runs.+ #[tokio::test]+ async fn test_commit_paths_mixed_file_and_dir_dedup() {+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));+ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct");+ std::fs::create_dir_all(acct_root.join("docs")).unwrap();+ std::fs::write(acct_root.join("docs/a.md"), b"AA").unwrap();+ std::fs::write(acct_root.join("docs/b.md"), b"BB").unwrap();+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());+ let svc = GitService::new(vfs, object_store, ref_store);++ let _ = make_commit(&svc, "acct", "main", "first").await;++ // Mutate one file, then commit with both an exact file path and+ // its parent directory.+ std::fs::write(acct_root.join("docs/a.md"), b"AA2").unwrap();+ let resp = svc+ .commit(req(+ "acct",+ "main",+ "mixed",+ Some(vec!["docs/a.md".into(), "docs".into()]),+ ))+ .await+ .unwrap();+ match resp {+ CommitResponse::Created { changed, .. } => {+ assert_eq!(changed, 1, "only docs/a.md content changed");+ }+ other => panic!("expected Created, got {other:?}"),+ }+ }++ // ── 9: show ────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_commit_meta_by_oid() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let oid = make_commit(&svc, "acct", "main", "first").await;++ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: oid.to_hex().to_string(),+ path: None,+ })+ .await+ .unwrap();++ match resp {+ ShowResponse::Commit {+ oid: returned,+ parents,+ message,+ author,+ committer,+ tree,+ } => {+ assert_eq!(returned, oid);+ assert!(parents.is_empty(), "root commit");+ assert_eq!(message, "first");+ assert_eq!(author.name, "tester");+ assert_eq!(author.email, "[email protected]");+ assert_eq!(committer.name, "tester");+ assert_ne!(tree, ObjectId::empty_tree(gix_hash::Kind::Sha1));+ }+ other => panic!("expected Commit, got {other:?}"),+ }+ }++ // ── 10 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_resolves_branch_name_and_full_ref() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let oid = make_commit(&svc, "acct", "main", "first").await;++ for tref in ["main", "refs/heads/main"] {+ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: tref.into(),+ path: None,+ })+ .await+ .unwrap();+ match resp {+ ShowResponse::Commit { oid: returned, .. } => assert_eq!(returned, oid),+ other => panic!("{tref}: expected Commit, got {other:?}"),+ }+ }+ }++ // ── 10b: abbreviated OID resolution ────────────────────────────────+ #[tokio::test]+ async fn test_show_resolves_short_oid_unique() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let oid = make_commit(&svc, "acct", "main", "first").await;+ let full = oid.to_hex().to_string();++ for len in [4usize, 7, 12, 39] {+ let short = &full[..len];+ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: short.into(),+ path: None,+ })+ .await+ .unwrap_or_else(|e| {+ panic!("short oid {short} (len {len}) should resolve, got {e}")+ });+ match resp {+ ShowResponse::Commit { oid: returned, .. } => assert_eq!(returned, oid),+ other => panic!("len {len}: expected Commit, got {other:?}"),+ }+ }+ }++ #[tokio::test]+ async fn test_show_short_oid_not_found_distinguished_from_branch() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ // A 4-hex string that almost-certainly does not match any commit.+ // (SHA-1 collision against a single commit is astronomically unlikely+ // for "ffff" — the first commit's hex is deterministic given the+ // test's actor/time-zero, so this is a stable miss.)+ let bogus = "ffff";+ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: bogus.into(),+ path: None,+ })+ .await+ .unwrap_err();+ assert!(+ matches!(err, GitError::OidPrefixNotFound { ref prefix } if prefix == bogus),+ "expected OidPrefixNotFound({bogus}), got {err:?}",+ );+ }++ #[tokio::test]+ async fn test_short_oid_three_chars_falls_through_to_ref_lookup() {+ // 3 hex chars is below the 4-char floor for abbreviated OID; it+ // should be treated as a branch name (which doesn't exist), giving+ // a RefStore::NotFound error — NOT OidPrefixNotFound.+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"hello");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "abc".into(),+ path: None,+ })+ .await+ .unwrap_err();+ assert!(+ matches!(err, GitError::RefStore(RefStoreError::NotFound(_))),+ "expected RefStore::NotFound for 3-char input, got {err:?}",+ );+ }++ // ── 11 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_blob_round_trip() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ let body = b"hello world\n";+ vfs.put("resources/a.md", body);+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/a.md".into()),+ })+ .await+ .unwrap();++ match resp {+ ShowResponse::Blob {+ bytes,+ size,+ oid: _,+ } => {+ assert_eq!(bytes.as_ref(), body);+ assert_eq!(size, body.len() as u64);+ }+ other => panic!("expected Blob, got {other:?}"),+ }+ }++ // ── 12 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_blob_path_not_found() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/missing.md".into()),+ })+ .await+ .unwrap_err();++ match err {+ GitError::PathNotFound(p) => assert_eq!(p, "resources/missing.md"),+ other => panic!("expected PathNotFound, got {other:?}"),+ }+ }++ // ── 13 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_blob_rejects_directory_path() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources".into()),+ })+ .await+ .unwrap_err();++ match err {+ GitError::PathIsDirectory(p) => assert_eq!(p, "resources"),+ other => panic!("expected PathIsDirectory, got {other:?}"),+ }+ }++ // ── 14 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_unknown_ref() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "nonexistent".into(),+ path: None,+ })+ .await+ .unwrap_err();++ match err {+ GitError::RefStore(RefStoreError::NotFound(name)) => {+ assert_eq!(name, "refs/heads/nonexistent");+ }+ other => panic!("expected RefStore NotFound, got {other:?}"),+ }+ }++ // ── 15 ─────────────────────────────────────────────────────────────+ #[tokio::test]+ async fn test_show_malformed_oid_input() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "z".repeat(40),+ path: None,+ })+ .await+ .unwrap_err();+ assert!(matches!(err, GitError::Other(_) | GitError::RefStore(_)));+ }++ // ── 16 ─────────────────────────────────────────────────────────────+ /// Blob bytes survive a round-trip even when they contain NUL bytes,+ /// non-UTF-8 sequences, and multiple newlines. Guards against any+ /// future "treat blobs as strings" regression.+ #[tokio::test]+ async fn test_show_blob_binary_and_multiline() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ // NUL, invalid UTF-8 (0xC3 0x28 is an invalid 2-byte sequence), CRLF, LF.+ let body: Vec<u8> = vec![+ b'h', b'i', 0x00, 0xC3, 0x28, b'\r', b'\n', b'l', b'i', b'n', b'e', b'2', b'\n', 0xFF,+ 0xFE, 0xFD,+ ];+ vfs.put("resources/bin.dat", &body);+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/bin.dat".into()),+ })+ .await+ .unwrap();++ match resp {+ ShowResponse::Blob { bytes, size, .. } => {+ assert_eq!(bytes, body);+ assert_eq!(size as usize, body.len());+ }+ other => panic!("expected Blob, got {other:?}"),+ }+ }++ // ── 17 ─────────────────────────────────────────────────────────────+ /// Construct a commit whose author and committer differ, write it+ /// directly via `util::write_object`, point a ref at it, and verify+ /// `show()` decodes the two signatures into the two Actor fields+ /// without crossing them. Bypasses `commit()` because the public+ /// `CommitRequest` API only accepts one author (used for both).+ #[tokio::test]+ async fn test_show_distinguishes_committer_from_author() {+ use gix_object::{bstr::BString, Commit, WriteTo};++ let (_dir, vfs, object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ // First, create a normal commit just to get a real tree OID.+ let seed_oid = make_commit(&svc, "acct", "main", "seed").await;+ let seed_tree =+ load_commit_meta(object_store.as_ref() as &dyn ObjectStore, "acct", &seed_oid)+ .await+ .unwrap()+ .tree;++ // Build a commit with deliberately mismatched author/committer.+ let author = gix_actor::Signature {+ name: "Alice Author".into(),+ email: "[email protected]".into(),+ time: gix_date::Time {+ seconds: 1_700_000_000,+ offset: 3600,+ sign: gix_date::time::Sign::Plus,+ },+ };+ let committer = gix_actor::Signature {+ name: "Carol Committer".into(),+ email: "[email protected]".into(),+ time: gix_date::Time {+ seconds: 1_700_000_100,+ offset: -7200,+ sign: gix_date::time::Sign::Minus,+ },+ };+ let commit = Commit {+ tree: seed_tree,+ parents: Vec::new().into(),+ author,+ committer,+ encoding: None,+ message: BString::from("split-actors"),+ extra_headers: Vec::new(),+ };+ let mut buf = Vec::new();+ commit.write_to(&mut buf).unwrap();+ let oid = crate::git::util::write_object(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ gix_object::Kind::Commit,+ &buf,+ )+ .await+ .unwrap();++ // Point a fresh branch at it so show() can find it by name.+ ref_store+ .cas_update("acct", "refs/heads/split", None, oid)+ .await+ .unwrap();++ let resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "split".into(),+ path: None,+ })+ .await+ .unwrap();++ match resp {+ ShowResponse::Commit {+ author, committer, ..+ } => {+ assert_eq!(author.name, "Alice Author");+ assert_eq!(author.email, "[email protected]");+ assert_eq!(author.time_seconds, 1_700_000_000);+ assert_eq!(author.tz_offset_seconds, 3600);+ assert_eq!(committer.name, "Carol Committer");+ assert_eq!(committer.email, "[email protected]");+ assert_eq!(committer.time_seconds, 1_700_000_100);+ assert_eq!(committer.tz_offset_seconds, -7200);+ }+ other => panic!("expected Commit, got {other:?}"),+ }+ }++ // ── 18 ─────────────────────────────────────────────────────────────+ /// When an intermediate path component is a blob (not a tree),+ /// `tree_builder::lookup` returns `Ok(None)`, which `show()` maps+ /// to `PathNotFound`. Pin this so a future change can't silently+ /// reinterpret it as `PathIsDirectory` or `CorruptedObject`.+ #[tokio::test]+ async fn test_show_intermediate_path_component_is_blob() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/a.md/oops".into()),+ })+ .await+ .unwrap_err();++ match err {+ GitError::PathNotFound(p) => assert_eq!(p, "resources/a.md/oops"),+ other => panic!("expected PathNotFound, got {other:?}"),+ }+ }++ // ── 19 ─────────────────────────────────────────────────────────────+ /// `show()` validates the `path` argument up front. Empty string, a+ /// leading or trailing `/`, and embedded `//` all fail+ /// `validate_relative_path` before any tree lookup runs — callers see+ /// `InvalidPath` rather than mixed `Other` / `PathNotFound` results.+ /// This pins the contract guarding the native binding boundary against+ /// traversal-style input (`..`, `/abs`, …) being silently accepted.+ #[tokio::test]+ async fn test_show_path_with_invalid_form() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ let _ = make_commit(&svc, "acct", "main", "first").await;++ for bad in ["", "/x", "x/", "a//b"] {+ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some(bad.into()),+ })+ .await+ .unwrap_err();+ assert!(+ matches!(err, GitError::InvalidPath(_)),+ "path {bad:?}: expected InvalidPath, got {err:?}",+ );+ }+ }++ // ── 20 ─────────────────────────────────────────────────────────────+ /// If the commit's loose object file is removed from the store+ /// after the ref still points at it, `show()` must surface+ /// `ObjectStoreError::NotFound` (wrapped in `GitError::ObjectStore`).+ /// Guards against any future "swallow missing objects" regression+ /// inside `load_commit_meta`.+ #[tokio::test]+ async fn test_show_commit_object_missing_from_store() {+ let (dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"x");+ let oid = make_commit(&svc, "acct", "main", "first").await;++ // LocalObjectStore layout: {base_dir}/{account}/objects/{aa}/{bb...}+ let hex = oid.to_hex().to_string();+ let path = dir+ .path()+ .join("acct")+ .join("objects")+ .join(&hex[..2])+ .join(&hex[2..]);+ std::fs::remove_file(&path).expect("loose commit object must exist before removal");++ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: None,+ })+ .await+ .unwrap_err();++ match err {+ GitError::ObjectStore(ObjectStoreError::NotFound(missing)) => {+ assert_eq!(missing, oid);+ }+ other => panic!("expected ObjectStore(NotFound), got {other:?}"),+ }+ }++ #[tokio::test]+ async fn test_mock_vfs_write_then_read_round_trip() {+ let vfs = MockVfs::new("acct");+ let path = "/local/acct/x.md";+ vfs.files+ .lock()+ .unwrap()+ .insert(path.to_string(), Vec::new());+ FileSystem::write(vfs.as_ref(), path, b"hello", 0, WriteFlag::Create)+ .await+ .unwrap();+ let got = FileSystem::read(vfs.as_ref(), path, 0, 0).await.unwrap();+ assert_eq!(got, b"hello");+ FileSystem::remove(vfs.as_ref(), path).await.unwrap();+ let err = FileSystem::read(vfs.as_ref(), path, 0, 0)+ .await+ .unwrap_err();+ assert!(matches!(err, Error::NotFound(_)));+ }++ // ── restore: dry_run ───────────────────────────────────────────────+ #[tokio::test]+ async fn test_restore_dry_run_reports_diff_and_writes_nothing() {+ let (_dir, vfs, object_store, ref_store, svc) = make_service("acct");+ // Source state: resources/proj_a has files a.md, b.md+ vfs.put("resources/proj_a/a.md", b"A v1");+ vfs.put("resources/proj_a/b.md", b"B v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD state: a.md is rewritten, b.md is deleted, c.md is created.+ // We pass explicit paths (including the deleted b.md) so commit()+ // sees the tombstone — collect_all() only enumerates surviving files.+ vfs.put("resources/proj_a/a.md", b"A v2");+ vfs.delete("resources/proj_a/b.md");+ vfs.put("resources/proj_a/c.md", b"C new");+ let head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: true,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ match resp {+ RestoreResponse::DryRun { diff, head, source } => {+ assert_eq!(source, source_oid);+ assert_eq!(head, head_oid);+ // a.md needs to roll back to v1, b.md needs to come back,+ // c.md needs to go away. Sorted alphabetically by path.+ assert_eq!(diff.to_write.len(), 2);+ assert_eq!(diff.to_write[0].0, "a.md");+ assert_eq!(diff.to_write[1].0, "b.md");+ assert_eq!(diff.to_delete, vec!["c.md".to_string()]);+ assert!(diff.unchanged.is_empty());+ }+ other => panic!("expected DryRun, got {other:?}"),+ }++ // CRITICAL: dry_run wrote nothing through the VFS — c.md and the v2+ // version of a.md must still be visible on disk.+ let files = vfs.files.lock().unwrap();+ assert_eq!(+ files.get("/local/acct/resources/proj_a/a.md").unwrap(),+ b"A v2",+ "dry_run must not overwrite a.md",+ );+ assert!(+ files.contains_key("/local/acct/resources/proj_a/c.md"),+ "dry_run must not delete c.md",+ );+ // Branch ref must still point at head_oid.+ let head_after = ref_store.read("acct", "refs/heads/main").await.unwrap();+ assert_eq!(head_after, head_oid);+ let _ = object_store; // silence unused warning+ }++ // ── restore: apply ─────────────────────────────────────────────────+ #[tokio::test]+ async fn test_restore_apply_writes_new_commit_with_head_as_parent() {+ let (_dir, vfs, object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/proj_a/a.md", b"A v1");+ vfs.put("resources/proj_a/b.md", b"B v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ vfs.put("resources/proj_a/a.md", b"A v2");+ vfs.delete("resources/proj_a/b.md");+ vfs.put("resources/proj_a/c.md", b"C new");+ // IMPORTANT: use explicit paths so the deletion of b.md is captured+ let head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind proj_a".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ let new_oid = match resp {+ RestoreResponse::Applied {+ new_commit_oid,+ source_commit,+ parent_commit,+ written,+ deleted,+ unchanged,+ written_paths,+ deleted_paths,+ } => {+ assert_eq!(source_commit, source_oid);+ assert_eq!(parent_commit, head_oid, "parent MUST be HEAD, NOT source");+ assert_eq!(written, 2, "a.md (rewrite) + b.md (recreate) = 2");+ assert_eq!(deleted, 1, "c.md");+ assert_eq!(unchanged, 0);+ assert_eq!(written_paths.len(), 2);+ assert_eq!(deleted_paths.len(), 1);+ // Paths should be account-relative (project_dir-prefixed).+ for p in &written_paths {+ assert!(+ p.starts_with("resources/proj_a/"),+ "written path missing project_dir prefix: {p}"+ );+ }+ for p in &deleted_paths {+ assert!(+ p.starts_with("resources/proj_a/"),+ "deleted path missing project_dir prefix: {p}"+ );+ }+ new_commit_oid+ }+ other => panic!("expected Applied, got {other:?}"),+ };++ // Ref now points at new_oid.+ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ new_oid+ );+ // New commit's parents = [head_oid] (NOT source_oid — this is the key+ // invariant of restore vs. plain checkout).+ let parents =+ commit_parents(object_store.as_ref() as &dyn ObjectStore, "acct", new_oid).await;+ assert_eq!(parents, vec![head_oid]);++ // VFS rolled back as expected.+ let files = vfs.files.lock().unwrap();+ assert_eq!(+ files.get("/local/acct/resources/proj_a/a.md").unwrap(),+ b"A v1",+ "a.md rolled back",+ );+ assert_eq!(+ files.get("/local/acct/resources/proj_a/b.md").unwrap(),+ b"B v1",+ "b.md restored",+ );+ assert!(+ !files.contains_key("/local/acct/resources/proj_a/c.md"),+ "c.md deleted",+ );+ }++ // Partial-writeback regression suite. Before this fix, a single failed+ // `FileSystem::write` (or non-NotFound `remove`) during step 10 would let+ // the ref keep pointing at the new commit while `try_collect` short-+ // circuited the rest of the writeback. The caller then saw a generic+ // RuntimeError and never scheduled reindex, leaving HEAD and the working+ // tree (and any vector index) inconsistent. These tests pin the new+ // behavior: every per-path op runs to completion and partial failures+ // surface as a structured `GitError::RestoreWritebackPartial`.++ /// A forced write failure for one path must produce+ /// `GitError::RestoreWritebackPartial` whose payload still reports the+ /// other writes/deletes as succeeded so the caller can reindex them.+ #[tokio::test]+ async fn test_restore_writeback_partial_returns_partial_error_on_write_failure() {+ let (_dir, vfs, _object_store, ref_store, svc) = make_service("acct");+ // Source: two files at v1.+ vfs.put("resources/proj_a/a.md", b"A v1");+ vfs.put("resources/proj_a/b.md", b"B v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD diverges: a.md updated, b.md updated, c.md added.+ vfs.put("resources/proj_a/a.md", b"A v2");+ vfs.put("resources/proj_a/b.md", b"B v2");+ vfs.put("resources/proj_a/c.md", b"C new");+ let _head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Force restore's writeback of a.md to fail. The diff also rewrites+ // b.md (success) and deletes c.md (success), so we expect a partial+ // error with exactly one failed write and the other operations+ // reported under the success buckets.+ vfs.fail_write("resources/proj_a/a.md");++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind partial".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect_err("restore must surface partial failure");++ let partial = match err {+ GitError::RestoreWritebackPartial(p) => p,+ other => panic!("expected RestoreWritebackPartial, got {other:?}"),+ };++ // Ref already advanced — partial must report the new HEAD so the+ // caller knows the commit is durable even though writeback failed.+ let head_after = ref_store.read("acct", "refs/heads/main").await.unwrap();+ assert_eq!(partial.new_commit_oid, head_after);++ assert_eq!(partial.failed_writes.len(), 1, "exactly one write failed");+ assert_eq!(partial.failed_writes[0].0, "resources/proj_a/a.md");+ assert!(+ !partial.failed_writes[0].1.is_empty(),+ "failure entry must carry a message"+ );+ assert!(partial.failed_deletes.is_empty(), "no deletes should fail");++ // The other write (b.md) succeeded and so must show up under+ // written_paths; c.md was deleted and lands under deleted_paths.+ assert_eq!(partial.written_paths, vec!["resources/proj_a/b.md"]);+ assert_eq!(partial.deleted_paths, vec!["resources/proj_a/c.md"]);+ assert_eq!(partial.written, 1);+ assert_eq!(partial.deleted, 1);+ }++ /// With two forced write failures we must still collect *both* — the+ /// stream must not short-circuit after the first one. This is the+ /// behavior change relative to the old `try_collect`.+ #[tokio::test]+ async fn test_restore_writeback_partial_continues_after_failure() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/proj_a/a.md", b"A v1");+ vfs.put("resources/proj_a/b.md", b"B v1");+ vfs.put("resources/proj_a/c.md", b"C v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ vfs.put("resources/proj_a/a.md", b"A v2");+ vfs.put("resources/proj_a/b.md", b"B v2");+ vfs.put("resources/proj_a/c.md", b"C v2");+ let _head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Two of the three writes fail.+ vfs.fail_write("resources/proj_a/a.md");+ vfs.fail_write("resources/proj_a/c.md");++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect_err("partial expected");++ let partial = match err {+ GitError::RestoreWritebackPartial(p) => p,+ other => panic!("expected RestoreWritebackPartial, got {other:?}"),+ };+ assert_eq!(+ partial.failed_writes.len(),+ 2,+ "stream must not short-circuit on the first failure"+ );+ let mut failed: Vec<String> = partial+ .failed_writes+ .iter()+ .map(|(p, _)| p.clone())+ .collect();+ failed.sort();+ assert_eq!(+ failed,+ vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]+ );+ // b.md still rolled back.+ assert_eq!(partial.written_paths, vec!["resources/proj_a/b.md"]);+ }++ /// A forced delete failure (non-NotFound) must surface in+ /// `failed_deletes` without aborting the rest of the stream.+ #[tokio::test]+ async fn test_restore_delete_failure_does_not_short_circuit() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ // Source has only a.md.+ vfs.put("resources/proj_a/a.md", b"A v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD adds b.md and c.md — restore must delete both.+ vfs.put("resources/proj_a/b.md", b"B new");+ vfs.put("resources/proj_a/c.md", b"C new");+ let _head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Force b.md's delete to fail; c.md must still be deleted.+ vfs.fail_remove("resources/proj_a/b.md");++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect_err("partial expected");++ let partial = match err {+ GitError::RestoreWritebackPartial(p) => p,+ other => panic!("expected RestoreWritebackPartial, got {other:?}"),+ };+ assert_eq!(partial.failed_deletes.len(), 1);+ assert_eq!(partial.failed_deletes[0].0, "resources/proj_a/b.md");+ assert_eq!(partial.deleted_paths, vec!["resources/proj_a/c.md"]);+ assert!(partial.failed_writes.is_empty());+ }++ /// `Error::NotFound` from `remove` is idempotent (the path was already+ /// gone) and must NOT count as a failure. With strict_remove enabled+ /// and a delete target that is already missing, restore must still+ /// return `Applied`.+ #[tokio::test]+ async fn test_restore_delete_notfound_not_counted_as_failure() {+ // Use new_strict_remove so absent paths produce NotFound rather than+ // silently succeeding — that's what the real LocalFileSystem does.+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new_strict_remove("acct");+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store.clone() as Arc<dyn RefStore>,+ );++ vfs.put("resources/proj_a/a.md", b"A v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ vfs.put("resources/proj_a/b.md", b"B new");+ let _head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Out-of-band: remove b.md from the VFS so the diff's delete plan+ // hits the NotFound path. Restore must still return Applied.+ vfs.delete("resources/proj_a/b.md");++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect("idempotent delete must stay on the Applied path");++ match resp {+ RestoreResponse::Applied {+ deleted_paths,+ deleted,+ ..+ } => {+ assert_eq!(+ deleted, 1,+ "b.md counts as deleted even though already gone"+ );+ assert_eq!(deleted_paths, vec!["resources/proj_a/b.md"]);+ }+ other => panic!("expected Applied, got {other:?}"),+ }+ }++ #[tokio::test]+ async fn test_restore_full_tree_apply_replaces_account_tree() {+ let (_dir, vfs, object_store, ref_store, svc) = make_service("acct");+ vfs.put("a.md", b"A v1");+ vfs.put("b.md", b"B v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ vfs.put("a.md", b"A v2");+ vfs.put("c.md", b"C new at head");+ vfs.delete("b.md");+ let head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "a.md".to_string(),+ "c.md".to_string(),+ "b.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: None,+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ let new_oid = match resp {+ RestoreResponse::Applied {+ new_commit_oid,+ source_commit,+ parent_commit,+ written,+ deleted,+ unchanged,+ written_paths,+ deleted_paths,+ } => {+ assert_eq!(source_commit, source_oid);+ assert_eq!(parent_commit, head_oid);+ assert_eq!(written, 2);+ assert_eq!(deleted, 1);+ assert_eq!(unchanged, 0);+ assert_eq!(written_paths, vec!["a.md".to_string(), "b.md".to_string()]);+ assert_eq!(deleted_paths, vec!["c.md".to_string()]);+ new_commit_oid+ }+ other => panic!("expected Applied, got {other:?}"),+ };++ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ new_oid+ );+ let parents =+ commit_parents(object_store.as_ref() as &dyn ObjectStore, "acct", new_oid).await;+ assert_eq!(parents, vec![head_oid]);++ let files = vfs.files.lock().unwrap();+ assert_eq!(files.get("/local/acct/a.md").unwrap(), b"A v1");+ assert_eq!(files.get("/local/acct/b.md").unwrap(), b"B v1");+ assert!(!files.contains_key("/local/acct/c.md"));+ }++ // Regression: restoring to a revision where a whole subdirectory's files+ // are gone must not leave an empty directory husk behind. Git does not+ // track directories, so the delete diff only lists files — restore is+ // responsible for pruning directories emptied by those deletes.+ //+ // Backed by a real `LocalFileSystem`: the in-memory `MockVfs` models+ // directories implicitly (deleting the last file makes the dir vanish for+ // free) and so cannot reproduce the husk. LocalFS keeps the directory on+ // disk, exactly like production, which is what makes this test meaningful.+ #[tokio::test]+ async fn test_restore_prunes_directories_emptied_by_delete() {+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));++ // Working tree root: /local/acct lives under this temp dir.+ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct");+ std::fs::create_dir_all(&acct_root).unwrap();+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());++ let svc = GitService::new(vfs.clone(), object_store.clone(), ref_store.clone());++ // Source commit: keeper.md at the project root only.+ std::fs::create_dir_all(acct_root.join("resources/proj_a")).unwrap();+ std::fs::write(acct_root.join("resources/proj_a/keeper.md"), b"keep").unwrap();+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD adds a nested subdir whose only files restore will delete.+ std::fs::create_dir_all(acct_root.join("resources/proj_a/nested/deep")).unwrap();+ std::fs::write(acct_root.join("resources/proj_a/nested/x.md"), b"x").unwrap();+ std::fs::write(acct_root.join("resources/proj_a/nested/deep/y.md"), b"y").unwrap();+ let _head_oid = make_commit(&svc, "acct", "main", "head").await;++ svc.restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ // Files are gone, and so are the now-empty directories that held them+ // (deepest first: deep/, then nested/).+ assert!(+ !acct_root.join("resources/proj_a/nested/deep/y.md").exists(),+ "nested/deep/y.md must be deleted",+ );+ assert!(+ !acct_root.join("resources/proj_a/nested/x.md").exists(),+ "nested/x.md must be deleted",+ );+ assert!(+ !acct_root.join("resources/proj_a/nested/deep").exists(),+ "emptied directory nested/deep must be pruned",+ );+ assert!(+ !acct_root.join("resources/proj_a/nested").exists(),+ "emptied directory nested must be pruned",+ );+ // The surviving file and its (non-empty) parent are untouched.+ assert!(+ acct_root.join("resources/proj_a/keeper.md").exists(),+ "keeper.md must survive",+ );+ assert!(+ acct_root.join("resources/proj_a").is_dir(),+ "project_dir itself must remain (still holds keeper.md)",+ );+ }++ // Regression: restoring to a source whose subtree contains files under a+ // directory that HEAD removed entirely (e.g. `rm -r` recorded as a commit+ // deletion) must recreate the missing directory chain before writing the+ // blobs back. Before `ensure_parent_dirs` was added to the writeback, this+ // aborted with `vfs: not found: .../resources/proj_a/nested`.+ #[tokio::test]+ async fn test_restore_recreates_directory_removed_by_head() {+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));++ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct");+ std::fs::create_dir_all(&acct_root).unwrap();+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());++ let svc = GitService::new(vfs.clone(), object_store.clone(), ref_store.clone());++ // Source commit: a nested directory with a file plus a top-level keeper.+ std::fs::create_dir_all(acct_root.join("resources/proj_a/nested/deep")).unwrap();+ std::fs::write(acct_root.join("resources/proj_a/keeper.md"), b"keep").unwrap();+ std::fs::write(acct_root.join("resources/proj_a/nested/x.md"), b"x v1").unwrap();+ std::fs::write(acct_root.join("resources/proj_a/nested/deep/y.md"), b"y v1").unwrap();+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD removes the whole `nested/` directory from disk (rm -r) and the+ // full-enumeration commit records the deletion, so HEAD's tree has no+ // `nested/` subtree at all.+ std::fs::remove_dir_all(acct_root.join("resources/proj_a/nested")).unwrap();+ assert!(!acct_root.join("resources/proj_a/nested").exists());+ let _head_oid = make_commit(&svc, "acct", "main", "head").await;++ // Restore back to source: the writeback must recreate `nested/` and+ // `nested/deep/` on disk before writing x.md / y.md.+ svc.restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ assert_eq!(+ std::fs::read(acct_root.join("resources/proj_a/nested/x.md")).unwrap(),+ b"x v1",+ "nested/x.md must be recreated with v1 content",+ );+ assert_eq!(+ std::fs::read(acct_root.join("resources/proj_a/nested/deep/y.md")).unwrap(),+ b"y v1",+ "nested/deep/y.md must be recreated with v1 content",+ );+ assert!(+ acct_root.join("resources/proj_a/keeper.md").exists(),+ "keeper.md must survive",+ );+ }++ // Regression: a path the restore diff wants to delete may already be absent+ // from the VFS (e.g. a derived file like `.abstract.md` removed out of+ // band). The delete must be idempotent — restore should succeed and advance+ // the branch ref rather than aborting with a `vfs: not found` error.+ #[tokio::test]+ async fn test_restore_tolerates_already_deleted_path() {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new_strict_remove("acct");+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store.clone() as Arc<dyn RefStore>,+ );++ // Source commit: a.md plus a derived file the diff will later delete.+ vfs.put("resources/proj_a/a.md", b"A v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD adds the derived file, so restoring source wants to delete it.+ vfs.put("resources/proj_a/.abstract.md", b"derived");+ vfs.put("resources/proj_a/a.md", b"A v2");+ let head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/.abstract.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Simulate the derived file vanishing from the VFS out of band, so the+ // restore's delete step hits a missing path.+ vfs.delete("resources/proj_a/.abstract.md");++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect("restore must tolerate an already-deleted path");++ let new_oid = match resp {+ RestoreResponse::Applied {+ deleted,+ deleted_paths,+ new_commit_oid,+ ..+ } => {+ // The diff still *plans* the delete (count is unchanged); the+ // VFS apply just no-ops on the missing path.+ assert_eq!(deleted, 1, ".abstract.md");+ assert_eq!(deleted_paths.len(), 1);+ new_commit_oid+ }+ other => panic!("expected Applied, got {other:?}"),+ };++ // Branch ref advanced to the new commit on top of HEAD.+ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ new_oid+ );+ let parents =+ commit_parents(object_store.as_ref() as &dyn ObjectStore, "acct", new_oid).await;+ assert_eq!(parents, vec![head_oid]);+ }++ #[tokio::test]+ async fn test_restore_noop_when_source_equals_head() {+ let (_dir, vfs, _object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/proj_a/a.md", b"only file");+ let only_oid = make_commit(&svc, "acct", "main", "only").await;++ // No further changes to proj_a — restoring from `only_oid` is a noop.+ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: only_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ match resp {+ RestoreResponse::Noop { head, source } => {+ assert_eq!(head, only_oid);+ assert_eq!(source, only_oid);+ }+ other => panic!("expected Noop, got {other:?}"),+ }+ // Ref unchanged.+ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ only_oid+ );+ }++ #[tokio::test]+ async fn test_restore_full_tree_dry_run_reports_account_relative_diff() {+ let (_dir, vfs, _object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"A v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ vfs.put("resources/a.md", b"A v2");+ vfs.put("memory/new.md", b"new");+ let head_oid = match svc+ .commit(req(+ "acct",+ "main",+ "head",+ Some(vec![+ "resources/a.md".to_string(),+ "memory/new.md".to_string(),+ ]),+ ))+ .await+ .unwrap()+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: None,+ source_commit: source_oid.to_hex().to_string(),+ dry_run: true,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ match resp {+ RestoreResponse::DryRun { diff, head, source } => {+ assert_eq!(head, head_oid);+ assert_eq!(source, source_oid);+ assert_eq!(diff.to_write.len(), 1);+ assert_eq!(diff.to_write[0].0, "resources/a.md");+ assert_eq!(diff.to_delete, vec!["memory/new.md".to_string()]);+ }+ other => panic!("expected DryRun, got {other:?}"),+ }++ let files = vfs.files.lock().unwrap();+ assert_eq!(files.get("/local/acct/resources/a.md").unwrap(), b"A v2");+ assert!(files.contains_key("/local/acct/memory/new.md"));+ drop(files);+ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ head_oid+ );+ }++ #[tokio::test]+ async fn test_restore_full_tree_noop_when_source_equals_head() {+ let (_dir, vfs, _object_store, ref_store, svc) = make_service("acct");+ vfs.put("resources/a.md", b"A v1");+ let head_oid = make_commit(&svc, "acct", "main", "source").await;++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: None,+ source_commit: head_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .unwrap();++ match resp {+ RestoreResponse::Noop { head, source } => {+ assert_eq!(head, head_oid);+ assert_eq!(source, head_oid);+ }+ other => panic!("expected Noop, got {other:?}"),+ }+ assert_eq!(+ ref_store.read("acct", "refs/heads/main").await.unwrap(),+ head_oid+ );+ }++ #[tokio::test]+ async fn test_restore_invalid_project_dir() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("".into()), // empty+ source_commit: "main".into(),+ dry_run: true,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ assert!(matches!(err, GitError::InvalidProjectDir(_)));+ }++ #[tokio::test]+ async fn test_restore_unknown_source_ref() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/proj_a/a.md", b"x");+ let _ = make_commit(&svc, "acct", "main", "init").await;+ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: "does-not-exist".into(),+ dry_run: true,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ assert!(matches!(+ err,+ GitError::RefStore(RefStoreError::NotFound(_))+ ));+ }++ #[tokio::test]+ async fn test_restore_unknown_branch_head() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ vfs.put("resources/proj_a/a.md", b"x");+ let only = make_commit(&svc, "acct", "main", "only").await;+ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "ghost".into(), // doesn't exist+ project_dir: Some("resources/proj_a".into()),+ source_commit: only.to_hex().to_string(),+ dry_run: true,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ assert!(matches!(+ err,+ GitError::RefStore(RefStoreError::NotFound(_))+ ));+ }++ #[tokio::test]+ async fn test_restore_project_dir_missing_in_source_commit() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");+ // Source commit only has resources/other_proj.+ vfs.put("resources/other_proj/x.md", b"x");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;+ // HEAD has the project we will try to restore.+ vfs.put("resources/proj_a/a.md", b"a");+ let _ = make_commit(&svc, "acct", "main", "head").await;++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: true,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ match err {+ GitError::SubtreeNotFoundInCommit {+ project_dir,+ commit,+ } => {+ assert_eq!(project_dir, "resources/proj_a");+ assert_eq!(commit, source_oid);+ }+ other => panic!("expected SubtreeNotFoundInCommit, got {other:?}"),+ }+ }++ #[tokio::test]+ async fn test_restore_cas_conflict_surfaces_as_error() {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let inner_ref = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new("acct");++ // Build a real first commit through a plain service so we have a HEAD.+ let bootstrap_svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ inner_ref.clone() as Arc<dyn RefStore>,+ );+ vfs.put("resources/proj_a/a.md", b"v1");+ let source_oid = make_commit(&bootstrap_svc, "acct", "main", "source").await;+ vfs.put("resources/proj_a/a.md", b"v2");+ let head_oid = make_commit(&bootstrap_svc, "acct", "main", "head").await;++ // Now wrap the ref store to force the first cas_update to fail.+ let bogus = ObjectId::from_hex(b"deadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap();+ let conflict_ref = Arc::new(ConflictOnceRef {+ inner: inner_ref.clone(),+ fired: Mutex::new(false),+ actual: Some(bogus),+ });+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ conflict_ref as Arc<dyn RefStore>,+ );++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ match err {+ GitError::ConcurrentCommit {+ ref_name,+ expected,+ actual,+ } => {+ assert_eq!(ref_name, "refs/heads/main");+ assert_eq!(expected, Some(head_oid));+ assert_eq!(actual, Some(bogus));+ }+ other => panic!("expected ConcurrentCommit, got {other:?}"),+ }+ }++ /// Regression: a losing CAS race during restore must leave the VFS+ /// byte-identical to its pre-restore (HEAD) state. The ref-consistency+ /// protocol now runs before any writeback, so a `ConcurrentCommit` error+ /// implies zero working-tree mutations — neither `to_write` content nor+ /// `to_delete` removals are applied. This keeps the failed request, the+ /// on-disk working tree, and the caller's reindex decision consistent.+ #[tokio::test]+ async fn test_restore_cas_conflict_leaves_vfs_unchanged() {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let inner_ref = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new("acct");++ let bootstrap_svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ inner_ref.clone() as Arc<dyn RefStore>,+ );++ // Source commit: a single file under the project dir.+ vfs.put("resources/proj_a/a.md", b"v1");+ let source_oid = make_commit(&bootstrap_svc, "acct", "main", "source").await;++ // HEAD commit: a.md is modified (would be a `to_write`) and a brand new+ // file is added (absent in source → would be a `to_delete` on restore).+ vfs.put("resources/proj_a/a.md", b"v2");+ vfs.put("resources/proj_a/b.md", b"new");+ let head_oid = make_commit(&bootstrap_svc, "acct", "main", "head").await;++ // Snapshot the working tree exactly as it stands at HEAD.+ let before = vfs.files.lock().unwrap().clone();++ // Force the first cas_update to conflict.+ let bogus = ObjectId::from_hex(b"deadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap();+ let conflict_ref = Arc::new(ConflictOnceRef {+ inner: inner_ref.clone(),+ fired: Mutex::new(false),+ actual: Some(bogus),+ });+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ conflict_ref as Arc<dyn RefStore>,+ );++ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap_err();+ assert!(+ matches!(err, GitError::ConcurrentCommit { .. }),+ "expected ConcurrentCommit, got {err:?}"+ );++ // The working tree must be untouched: a.md still v2 (not rewritten to+ // v1) and b.md still present (not deleted).+ let after = vfs.files.lock().unwrap().clone();+ assert_eq!(after, before, "VFS must not change on a CAS conflict");+ assert_eq!(+ after+ .get("/local/acct/resources/proj_a/a.md")+ .map(|v| v.as_slice()),+ Some(b"v2".as_slice()),+ "a.md must keep its HEAD content"+ );+ assert!(+ after.contains_key("/local/acct/resources/proj_a/b.md"),+ "b.md must not be deleted"+ );++ // And HEAD must still point at the original commit.+ let head_now = inner_ref.read("acct", "refs/heads/main").await.unwrap();+ assert_eq!(head_now, head_oid, "branch ref must be unchanged");+ }++ #[tokio::test]+ async fn test_restore_does_not_touch_paths_outside_project_dir() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct");++ // Source: resources/proj_a + an UNRELATED file in another scope.+ vfs.put("resources/proj_a/a.md", b"A v1");+ vfs.put("agent/skills/unrelated.py", b"unrelated v1");+ let source_oid = make_commit(&svc, "acct", "main", "source").await;++ // HEAD: modify proj_a AND the unrelated file. Note we don't delete+ // anything in this test, so make_commit (which uses collect_all) is+ // fine — all files still exist in the VFS.+ vfs.put("resources/proj_a/a.md", b"A v2");+ vfs.put("agent/skills/unrelated.py", b"unrelated v2");+ vfs.put("agent/skills/new_skill.py", b"brand new");+ let _ = make_commit(&svc, "acct", "main", "head").await;++ let resp = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: None,+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap();++ let new_oid = match resp {+ RestoreResponse::Applied { new_commit_oid, .. } => new_commit_oid,+ other => panic!("expected Applied, got {other:?}"),+ };++ // Verify the VFS: unrelated files keep their v2 / new state.+ let files = vfs.files.lock().unwrap();+ assert_eq!(+ files.get("/local/acct/agent/skills/unrelated.py").unwrap(),+ b"unrelated v2",+ "restore must NOT roll back unrelated.py",+ );+ assert!(+ files.contains_key("/local/acct/agent/skills/new_skill.py"),+ "restore must NOT delete new_skill.py",+ );+ // And proj_a/a.md DID roll back.+ assert_eq!(+ files.get("/local/acct/resources/proj_a/a.md").unwrap(),+ b"A v1",+ );+ drop(files);++ // Verify the tree: the new commit's tree should contain the v2 content+ // of unrelated.py and new_skill.py at their original oids. The easiest+ // way: lookup the oid of agent/skills/unrelated.py in both source and+ // new — they must DIFFER (source had v1, new still has v2).+ let new_tree =+ load_commit_meta(object_store.as_ref() as &dyn ObjectStore, "acct", &new_oid)+ .await+ .unwrap()+ .tree;+ let source_tree = load_commit_meta(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ &source_oid,+ )+ .await+ .unwrap()+ .tree;+ let unrelated_in_new = crate::git::tree_builder::lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ new_tree,+ "agent/skills/unrelated.py",+ )+ .await+ .unwrap()+ .unwrap();+ let unrelated_in_source = crate::git::tree_builder::lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ source_tree,+ "agent/skills/unrelated.py",+ )+ .await+ .unwrap()+ .unwrap();+ assert_ne!(+ unrelated_in_new.0, unrelated_in_source.0,+ "agent/skills/unrelated.py in the new tree must be HEAD's v2 oid, not source's v1 oid",+ );+ assert!(+ crate::git::tree_builder::lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct",+ new_tree,+ "agent/skills/new_skill.py",+ )+ .await+ .unwrap()+ .is_some(),+ "new_skill.py must still be present in the new tree",+ );+ }++ #[tokio::test]+ async fn test_restore_then_show_reflects_old_content() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct");++ vfs.put("resources/proj_a/note.md", b"original");+ let src = make_commit(&svc, "acct", "main", "src").await;++ vfs.put("resources/proj_a/note.md", b"edited");+ let _ = make_commit(&svc, "acct", "main", "edit").await;++ // Sanity: show on HEAD shows "edited".+ let head_show = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/proj_a/note.md".into()),+ })+ .await+ .unwrap();+ match head_show {+ ShowResponse::Blob { bytes, .. } => assert_eq!(bytes.as_ref(), b"edited"),+ other => panic!("expected Blob, got {other:?}"),+ }++ // Restore.+ let new_oid = match svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: src.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind".into()),+ author_name: "x".into(),+ author_email: "x@x".into(),+ })+ .await+ .unwrap()+ {+ RestoreResponse::Applied { new_commit_oid, .. } => new_commit_oid,+ other => panic!("expected Applied, got {other:?}"),+ };++ // After restore: show on main should reflect the original content.+ let after_show = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("resources/proj_a/note.md".into()),+ })+ .await+ .unwrap();+ match after_show {+ ShowResponse::Blob { bytes, .. } => assert_eq!(bytes.as_ref(), b"original"),+ other => panic!("expected Blob, got {other:?}"),+ }++ // And show on the new oid by hex resolves to the same content.+ let by_oid = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: new_oid.to_hex().to_string(),+ path: Some("resources/proj_a/note.md".into()),+ })+ .await+ .unwrap();+ match by_oid {+ ShowResponse::Blob { bytes, .. } => assert_eq!(bytes.as_ref(), b"original"),+ other => panic!("expected Blob, got {other:?}"),+ }+ }++ // ── Fast Path 3: blob exists precheck ───────────────────────────────+ /// ObjectStore wrapper that counts `put` / `exists` calls, delegating to+ /// an inner `LocalObjectStore`.+ struct CountingObjectStore {+ inner: LocalObjectStore,+ puts: std::sync::atomic::AtomicUsize,+ exists_calls: std::sync::atomic::AtomicUsize,+ }++ #[async_trait]+ impl ObjectStore for CountingObjectStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: bytes::Bytes,+ ) -> std::result::Result<(), ObjectStoreError> {+ self.puts.fetch_add(1, std::sync::atomic::Ordering::SeqCst);+ self.inner.put(account, oid, zlib_body).await+ }+ async fn get(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> std::result::Result<bytes::Bytes, ObjectStoreError> {+ self.inner.get(account, oid).await+ }+ async fn exists(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> std::result::Result<bool, ObjectStoreError> {+ self.exists_calls+ .fetch_add(1, std::sync::atomic::Ordering::SeqCst);+ self.inner.exists(account, oid).await+ }+ }++ #[tokio::test]+ async fn test_commit_fast_path_3_skips_put_for_duplicate_blob() {+ use std::sync::atomic::Ordering;+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(CountingObjectStore {+ inner: LocalObjectStore::new(dir.path()),+ puts: std::sync::atomic::AtomicUsize::new(0),+ exists_calls: std::sync::atomic::AtomicUsize::new(0),+ });+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new("acct");+ // No index store → slow path runs → Fast Path 3 active (default on).+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ );++ vfs.put("a.md", b"dup");+ svc.commit(req("acct", "main", "first", None))+ .await+ .unwrap();++ // Commit a second file with identical content → same blob oid. The+ // blob `put` must be skipped (exists hit); only the new root tree and+ // commit object are written (2 puts, no blob put).+ vfs.put("b.md", b"dup");+ let puts_before = object_store.puts.load(Ordering::SeqCst);+ let exists_before = object_store.exists_calls.load(Ordering::SeqCst);+ svc.commit(req("acct", "main", "second", Some(vec!["b.md".into()])))+ .await+ .unwrap();+ let put_delta = object_store.puts.load(Ordering::SeqCst) - puts_before;++ // exists() was consulted on the second commit's slow path.+ assert!(object_store.exists_calls.load(Ordering::SeqCst) > exists_before);+ // Only tree + commit objects were put — the duplicate blob was skipped.+ assert_eq!(put_delta, 2, "duplicate blob must not be re-put");+ }++ #[tokio::test]+ async fn test_commit_fast_path_3_disabled_reputs_duplicate_blob() {+ use std::sync::atomic::Ordering;+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(CountingObjectStore {+ inner: LocalObjectStore::new(dir.path()),+ puts: std::sync::atomic::AtomicUsize::new(0),+ exists_calls: std::sync::atomic::AtomicUsize::new(0),+ });+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new("acct");+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ )+ .with_blob_exists_precheck(false);++ vfs.put("a.md", b"dup");+ svc.commit(req("acct", "main", "first", None))+ .await+ .unwrap();+ let exists_after_first = object_store.exists_calls.load(Ordering::SeqCst);++ vfs.put("b.md", b"dup");+ let puts_before = object_store.puts.load(Ordering::SeqCst);+ svc.commit(req("acct", "main", "second", Some(vec!["b.md".into()])))+ .await+ .unwrap();++ // With precheck off, the slow path calls write_object unconditionally+ // → at least one put for the dup blob (idempotent at the backend).+ assert!(object_store.puts.load(Ordering::SeqCst) > puts_before);+ // And no extra exists() calls were issued from the blob write path on+ // the second commit (precheck disabled). The backend's own put+ // idempotency uses try_exists internally, not ObjectStore::exists.+ assert_eq!(+ object_store.exists_calls.load(Ordering::SeqCst),+ exists_after_first+ );++ // Result correctness: both files resolve to the same content.+ let show_b = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some("b.md".into()),+ })+ .await+ .unwrap();+ match show_b {+ ShowResponse::Blob { bytes, .. } => assert_eq!(bytes.as_ref(), b"dup"),+ other => panic!("expected Blob, got {other:?}"),+ }+ }++ // ── prev_tree lookup cache: each ancestor tree loaded once per commit ──+ /// ObjectStore wrapper that records every `get` oid so we can prove the+ /// commit loop re-fetches each prev_tree subtree at most once.+ struct GetSpyObjectStore {+ inner: LocalObjectStore,+ gets: std::sync::Mutex<Vec<ObjectId>>,+ }++ impl GetSpyObjectStore {+ fn count_gets(&self, oid: &ObjectId) -> usize {+ self.gets+ .lock()+ .unwrap()+ .iter()+ .filter(|o| *o == oid)+ .count()+ }+ fn reset(&self) {+ self.gets.lock().unwrap().clear();+ }+ }++ #[async_trait]+ impl ObjectStore for GetSpyObjectStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: bytes::Bytes,+ ) -> std::result::Result<(), ObjectStoreError> {+ self.inner.put(account, oid, zlib_body).await+ }+ async fn get(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> std::result::Result<bytes::Bytes, ObjectStoreError> {+ self.gets.lock().unwrap().push(*oid);+ self.inner.get(account, oid).await+ }+ async fn exists(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> std::result::Result<bool, ObjectStoreError> {+ self.inner.exists(account, oid).await+ }+ }++ #[tokio::test]+ async fn test_commit_prev_tree_lookup_cache_amortises_ancestors() {+ // Build a prev tree where many candidates share the same depth-3+ // ancestor chain (root → resources → docs). Without the lookup cache,+ // each candidate would re-fetch all three trees from object_store on+ // its `lookup(prev_tree, ...)` call. With the cache, every ancestor+ // along that chain is fetched at most once for the whole commit.+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(GetSpyObjectStore {+ inner: LocalObjectStore::new(dir.path()),+ gets: std::sync::Mutex::new(Vec::new()),+ });+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = MockVfs::new("acct");+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store.clone() as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ );++ // First commit: seed prev_tree with 5 files all under resources/docs/.+ for name in ["a", "b", "c", "d", "e"] {+ vfs.put(&format!("resources/docs/{}.md", name), name.as_bytes());+ }+ svc.commit(req("acct", "main", "seed", None)).await.unwrap();++ // Capture root tree oid and its ancestor chain to resources/docs.+ let head_resp = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: None,+ })+ .await+ .unwrap();+ let root_tree_oid = match head_resp {+ ShowResponse::Commit { tree, .. } => tree,+ _ => panic!("expected commit"),+ };+ // Resolve resources/docs tree oid by walking root once.+ let mut cache = crate::git::tree_builder::TreeLookupCache::new();+ let (resources_oid, _) = crate::git::tree_builder::lookup_cached(+ object_store.as_ref(),+ "acct",+ root_tree_oid,+ "resources",+ &mut cache,+ )+ .await+ .unwrap()+ .unwrap();+ let (docs_oid, _) = crate::git::tree_builder::lookup_cached(+ object_store.as_ref(),+ "acct",+ root_tree_oid,+ "resources/docs",+ &mut cache,+ )+ .await+ .unwrap()+ .unwrap();++ // Reset spy, then run a commit that touches all 5 candidates with the+ // same content (so every Fast Path 1 miss path runs the prev lookup+ // for the no-op skip check). The assertion proves each ancestor tree+ // is fetched at most once across all 5 lookups.+ object_store.reset();+ let candidates: Vec<String> = ["a", "b", "c", "d", "e"]+ .iter()+ .map(|n| format!("resources/docs/{}.md", n))+ .collect();+ svc.commit(req("acct", "main", "rewrite", Some(candidates)))+ .await+ .unwrap();++ // Each ancestor on the prev_tree chain was fetched at most once.+ assert!(+ object_store.count_gets(&root_tree_oid) <= 1,+ "root tree was fetched {} times, expected ≤1 (cache miss)",+ object_store.count_gets(&root_tree_oid)+ );+ assert!(+ object_store.count_gets(&resources_oid) <= 1,+ "resources tree was fetched {} times, expected ≤1 (cache miss)",+ object_store.count_gets(&resources_oid)+ );+ assert!(+ object_store.count_gets(&docs_oid) <= 1,+ "resources/docs tree was fetched {} times, expected ≤1 (cache miss)",+ object_store.count_gets(&docs_oid)+ );+ }++ // ── account id validation ───────────────────────────────────────────+ #[test]+ fn validate_account_id_accepts_valid() {+ for ok in ["acct", "a", "user-1", "u_2", "name.tag", "a@b", "ABC123"] {+ assert!(validate_account_id(ok).is_ok(), "{ok:?} should be valid");+ }+ }++ #[test]+ fn validate_account_id_rejects_malicious() {+ for bad in [+ "", // empty+ ".", // dot+ "..", // parent+ "../x", // traversal+ "a/b", // slash+ "a\\b", // backslash+ "a\0b", // NUL+ "a\nb", // newline / control+ "a b", // space+ "a@b@c", // multiple @+ "_system", // leading underscore+ ] {+ assert!(+ matches!(validate_account_id(bad), Err(GitError::InvalidAccountId(_))),+ "{bad:?} should be rejected",+ );+ }+ }++ #[tokio::test]+ async fn commit_rejects_traversal_account() {+ // A crafted account must be rejected before any path is built, so the+ // ref store is never even touched.+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc.commit(req("../escape", "main", "msg", None)).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn commit_rejects_slash_account() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc.commit(req("a/b", "main", "msg", None)).await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn show_rejects_traversal_account() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc+ .show(ShowRequest {+ account: "../escape".into(),+ target_ref: "main".into(),+ path: None,+ })+ .await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ #[tokio::test]+ async fn restore_rejects_traversal_account() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ let err = svc+ .restore(RestoreRequest {+ account: "../escape".into(),+ branch: "main".into(),+ project_dir: Some("resources/x".into()),+ source_commit: "deadbeef".into(),+ dry_run: false,+ message: None,+ author_name: "n".into(),+ author_email: "e".into(),+ })+ .await;+ assert!(matches!(err, Err(GitError::InvalidAccountId(_))));+ }++ // ── direct-binding traversal defence: account is OK, but the caller+ // tries to escape via paths / project_dir / show path. These must be+ // rejected before any VFS / object-store I/O. ──────────────────────+ #[tokio::test]+ async fn commit_rejects_traversal_in_paths() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ for bad in [+ "../other/file.md",+ "a/../../other.md",+ "/abs.md",+ "a/./b.md",+ "a\\b.md",+ ] {+ let err = svc+ .commit(req("acct", "main", "msg", Some(vec![bad.to_string()])))+ .await;+ assert!(+ matches!(err, Err(GitError::InvalidPath(_))),+ "{bad:?} should yield InvalidPath, got {err:?}",+ );+ }+ }++ #[tokio::test]+ async fn show_rejects_traversal_path() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ for bad in ["../other.md", ".", "..", "a/../b", ""] {+ let err = svc+ .show(ShowRequest {+ account: "acct".into(),+ target_ref: "main".into(),+ path: Some(bad.to_string()),+ })+ .await;+ assert!(+ matches!(err, Err(GitError::InvalidPath(_))),+ "{bad:?} should yield InvalidPath, got {err:?}",+ );+ }+ }++ #[tokio::test]+ async fn restore_rejects_traversal_project_dir() {+ let (_dir, _vfs, _object_store, _ref_store, svc) = make_service("acct");+ for bad in ["../other", ".", "..", "a/../b", "a/./b", "a\\b"] {+ let err = svc+ .restore(RestoreRequest {+ account: "acct".into(),+ branch: "main".into(),+ project_dir: Some(bad.to_string()),+ source_commit: "deadbeef".into(),+ dry_run: false,+ message: None,+ author_name: "n".into(),+ author_email: "e".into(),+ })+ .await;+ assert!(+ matches!(err, Err(GitError::InvalidProjectDir(_))),+ "{bad:?} should yield InvalidProjectDir, got {err:?}",+ );+ }+ }+}++#[cfg(test)]+mod diff_tests {+ use super::*;+ use crate::git::types::RestoreDiff;+ use gix_hash::ObjectId;++ fn oid(byte: u8) -> ObjectId {+ let mut bytes = [0u8; 20];+ bytes.fill(byte);+ ObjectId::from_bytes_or_panic(&bytes)+ }++ #[test]+ fn diff_empty_both() {+ let got = compute_subtree_diff(&[], &[]);+ assert_eq!(+ got,+ RestoreDiff {+ to_write: vec![],+ to_delete: vec![],+ unchanged: vec![]+ }+ );+ }++ #[test]+ fn diff_all_writes_when_head_empty() {+ let source = vec![("a.md".to_string(), oid(0xAA))];+ let got = compute_subtree_diff(&source, &[]);+ assert_eq!(got.to_write, vec![("a.md".to_string(), oid(0xAA))]);+ assert!(got.to_delete.is_empty());+ assert!(got.unchanged.is_empty());+ }++ #[test]+ fn diff_all_deletes_when_source_empty() {+ let head = vec![("b.md".to_string(), oid(0xBB))];+ let got = compute_subtree_diff(&[], &head);+ assert!(got.to_write.is_empty());+ assert_eq!(got.to_delete, vec!["b.md".to_string()]);+ assert!(got.unchanged.is_empty());+ }++ #[test]+ fn diff_unchanged_same_oid_same_path() {+ let entries = vec![("a.md".to_string(), oid(0xCC))];+ let got = compute_subtree_diff(&entries, &entries);+ assert!(got.to_write.is_empty());+ assert!(got.to_delete.is_empty());+ assert_eq!(got.unchanged, vec!["a.md".to_string()]);+ }++ #[test]+ fn diff_overwrite_when_same_path_different_oid() {+ let source = vec![("a.md".to_string(), oid(0xAA))];+ let head = vec![("a.md".to_string(), oid(0xBB))];+ let got = compute_subtree_diff(&source, &head);+ assert_eq!(got.to_write, vec![("a.md".to_string(), oid(0xAA))]);+ assert!(got.to_delete.is_empty());+ assert!(got.unchanged.is_empty());+ }++ #[test]+ fn diff_mixed_buckets_sorted_deterministically() {+ let source = vec![+ ("keep.md".to_string(), oid(0x11)),+ ("change.md".to_string(), oid(0x22)),+ ("new.md".to_string(), oid(0x33)),+ ];+ let head = vec![+ ("keep.md".to_string(), oid(0x11)),+ ("change.md".to_string(), oid(0x99)),+ ("gone.md".to_string(), oid(0x44)),+ ];+ let got = compute_subtree_diff(&source, &head);+ assert_eq!(+ got.to_write,+ vec![+ ("change.md".to_string(), oid(0x22)),+ ("new.md".to_string(), oid(0x33)),+ ]+ );+ assert_eq!(got.to_delete, vec!["gone.md".to_string()]);+ assert_eq!(got.unchanged, vec!["keep.md".to_string()]);+ }++ #[test]+ fn diff_handles_nested_paths() {+ let source = vec![+ ("docs/a.md".to_string(), oid(0xAA)),+ ("docs/sub/b.md".to_string(), oid(0xBB)),+ ];+ let head = vec![("docs/a.md".to_string(), oid(0xAA))];+ let got = compute_subtree_diff(&source, &head);+ assert_eq!(got.to_write, vec![("docs/sub/b.md".to_string(), oid(0xBB))]);+ assert!(got.to_delete.is_empty());+ assert_eq!(got.unchanged, vec!["docs/a.md".to_string()]);+ }++ #[test]+ fn validate_rejects_empty_string() {+ let err = validate_project_dir("").unwrap_err();+ assert!(matches!(err, GitError::InvalidProjectDir(_)));+ }++ #[test]+ fn validate_rejects_leading_slash() {+ assert!(matches!(+ validate_project_dir("/resources/proj_a").unwrap_err(),+ GitError::InvalidProjectDir(_)+ ));+ }++ #[test]+ fn validate_rejects_trailing_slash() {+ assert!(matches!(+ validate_project_dir("resources/proj_a/").unwrap_err(),+ GitError::InvalidProjectDir(_)+ ));+ }++ #[test]+ fn validate_rejects_double_slash() {+ assert!(matches!(+ validate_project_dir("resources//proj_a").unwrap_err(),+ GitError::InvalidProjectDir(_)+ ));+ }++ #[test]+ fn validate_accepts_simple_path() {+ validate_project_dir("resources/proj_a").unwrap();+ }++ #[test]+ fn validate_accepts_single_segment() {+ validate_project_dir("resources").unwrap();+ }++ // ── project_dir hardening (traversal / backslash / control) ─────────+ #[test]+ fn validate_project_dir_rejects_dotdot_segment() {+ for bad in ["..", "../other", "resources/../other", "a/.."] {+ assert!(+ matches!(+ validate_project_dir(bad),+ Err(GitError::InvalidProjectDir(_))+ ),+ "{bad:?} should be rejected",+ );+ }+ }++ #[test]+ fn validate_project_dir_rejects_dot_segment() {+ for bad in [".", "./x", "a/./b"] {+ assert!(matches!(+ validate_project_dir(bad),+ Err(GitError::InvalidProjectDir(_))+ ));+ }+ }++ #[test]+ fn validate_project_dir_rejects_backslash_and_control() {+ for bad in ["a\\b", "a\0b", "a\nb"] {+ assert!(+ matches!(+ validate_project_dir(bad),+ Err(GitError::InvalidProjectDir(_))+ ),+ "{bad:?} should be rejected",+ );+ }+ }++ // ── relative path validation (commit / show) ────────────────────────+ #[test]+ fn validate_relative_path_accepts_normal_paths() {+ for ok in ["a.md", "dir/a.md", "a/b/c/d.txt", "..hidden", "a..b"] {+ validate_relative_path(ok)+ .unwrap_or_else(|e| panic!("{ok:?} should be valid, got {e:?}"));+ }+ }++ #[test]+ fn validate_relative_path_rejects_malicious() {+ for bad in [+ "", // empty+ "/abs/path", // leading slash+ "trailing/", // trailing slash+ "a//b", // empty segment+ ".", // dot+ "..", // dotdot+ "../escape", // traversal at root+ "a/../b", // traversal mid-path+ "a/./b", // dot mid-path+ "a\\b", // backslash+ "a\0b", // NUL+ "a\nb", // control char+ ] {+ assert!(+ matches!(validate_relative_path(bad), Err(GitError::InvalidPath(_))),+ "{bad:?} should be rejected",+ );+ }+ }+}++#[cfg(test)]+mod fast_path1_tests {+ //! Tests for Fast Path 1 (the persistent stat cache). The strategy:+ //! - Wrap `MockFsCounting` around a tiny in-memory map with controllable+ //! `mod_time` per path AND a `reads` counter.+ //! - Wrap `LocalIndexStore` in a temp dir as the index backend.+ //! - Run two commits and assert `reads` only goes up by the expected+ //! amount on the second one.+ //!+ //! Each assertion pins a distinct invariant of Fast Path 1: cache hit+ //! skips read; (size, mtime_ns) mismatch invalidates; parent_oid mismatch+ //! disables the cache; corruption is silent; partial-paths preserves+ //! uncovered entries; deletion removes entries.+ use super::*;+ use async_trait::async_trait;+ use std::collections::HashMap;+ use std::sync::atomic::{AtomicU64, Ordering};+ use std::sync::{Arc, Mutex};+ use std::time::{Duration, SystemTime, UNIX_EPOCH};++ use crate::core::errors::{Error, Result};+ use crate::core::filesystem::FileSystem;+ use crate::core::types::{FileInfo, TreeEntry, WriteFlag};+ use crate::git::backends::local::{LocalIndexStore, LocalObjectStore, LocalRefStore};+ use crate::git::index_store::IndexStore;++ struct CountingVfs {+ account: String,+ // path -> (bytes, mtime_ns)+ files: Arc<Mutex<HashMap<String, (Vec<u8>, i128)>>>,+ reads: AtomicU64,+ }++ impl CountingVfs {+ fn new(account: &str) -> Arc<Self> {+ Arc::new(Self {+ account: account.to_string(),+ files: Arc::new(Mutex::new(HashMap::new())),+ reads: AtomicU64::new(0),+ })+ }++ fn put(&self, rel: &str, data: &[u8], mtime_ns: i128) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.files+ .lock()+ .unwrap()+ .insert(abs, (data.to_vec(), mtime_ns));+ }++ fn delete(&self, rel: &str) {+ let abs = format!("/local/{}/{}", self.account, rel);+ self.files.lock().unwrap().remove(&abs);+ }++ fn reads(&self) -> u64 {+ self.reads.load(Ordering::SeqCst)+ }+ }++ fn nanos_to_systemtime(ns: i128) -> SystemTime {+ // Tests use small positive nanos, so the cast is lossless.+ let secs = (ns / 1_000_000_000) as u64;+ let sub = (ns % 1_000_000_000) as u32;+ UNIX_EPOCH + Duration::new(secs, sub)+ }++ #[async_trait]+ impl FileSystem for CountingVfs {+ async fn create(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }+ async fn mkdir(&self, _path: &str, _mode: u32) -> Result<()> {+ unimplemented!()+ }+ async fn remove(&self, path: &str) -> Result<()> {+ self.files.lock().unwrap().remove(path);+ Ok(())+ }+ async fn remove_all(&self, _path: &str) -> Result<()> {+ unimplemented!()+ }++ async fn read(&self, path: &str, _offset: u64, _size: u64) -> Result<Vec<u8>> {+ let g = self.files.lock().unwrap();+ match g.get(path) {+ Some((bytes, _)) => {+ self.reads.fetch_add(1, Ordering::SeqCst);+ Ok(bytes.clone())+ }+ None => Err(Error::not_found(path)),+ }+ }++ async fn write(+ &self,+ path: &str,+ data: &[u8],+ _offset: u64,+ _flags: WriteFlag,+ ) -> Result<u64> {+ self.files+ .lock()+ .unwrap()+ .insert(path.to_string(), (data.to_vec(), 0));+ Ok(data.len() as u64)+ }+ async fn read_dir(&self, _path: &str) -> Result<Vec<FileInfo>> {+ unimplemented!()+ }++ async fn stat(&self, path: &str) -> Result<FileInfo> {+ let g = self.files.lock().unwrap();+ if let Some((bytes, mtime_ns)) = g.get(path) {+ let name = path.rsplit('/').next().unwrap_or(path).to_string();+ return Ok(FileInfo::new(+ name,+ bytes.len() as u64,+ 0o644,+ nanos_to_systemtime(*mtime_ns),+ false,+ ));+ }+ Err(Error::not_found(path))+ }++ async fn rename(&self, _o: &str, _n: &str) -> Result<()> {+ unimplemented!()+ }+ async fn chmod(&self, _path: &str, _mode: u32) -> Result<()> {+ unimplemented!()+ }++ async fn tree_directory(+ &self,+ path: &str,+ _show_hidden: bool,+ _node_limit: Option<usize>,+ _level_limit: Option<usize>,+ ) -> Result<Vec<TreeEntry>> {+ let prefix = if path == "/" {+ "/".to_string()+ } else {+ format!("{}/", path)+ };+ let g = self.files.lock().unwrap();+ let mut out = Vec::new();+ for (full_path, (_bytes, _mtime)) in g.iter() {+ if !full_path.starts_with(&prefix) {+ continue;+ }+ let rel = full_path+ .strip_prefix(&prefix)+ .unwrap_or(full_path)+ .to_string();+ let name = full_path+ .rsplit('/')+ .next()+ .unwrap_or(full_path)+ .to_string();+ out.push(TreeEntry {+ path: full_path.clone(),+ rel_path: rel,+ info: FileInfo::new_file(name, 0, 0o644),+ extra: HashMap::new(),+ });+ }+ Ok(out)+ }+ }++ fn make_service_with_index(+ account: &str,+ ) -> (+ tempfile::TempDir,+ Arc<CountingVfs>,+ Arc<LocalIndexStore>,+ GitService,+ ) {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let index_store = Arc::new(LocalIndexStore::new(dir.path()));+ let vfs = CountingVfs::new(account);+ let svc = GitService::with_index(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ Some(index_store.clone() as Arc<dyn IndexStore>),+ );+ (dir, vfs, index_store, svc)+ }++ fn make_service_no_index(account: &str) -> (tempfile::TempDir, Arc<CountingVfs>, GitService) {+ let dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(dir.path()));+ let vfs = CountingVfs::new(account);+ let svc = GitService::new(+ vfs.clone() as Arc<dyn FileSystem>,+ object_store as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ );+ (dir, vfs, svc)+ }++ fn req(account: &str, branch: &str, paths: Option<Vec<String>>) -> CommitRequest {+ CommitRequest {+ account: account.to_string(),+ branch: branch.to_string(),+ message: "m".to_string(),+ paths,+ author_name: "tester".to_string(),+ author_email: "t@x".to_string(),+ }+ }++ #[tokio::test]+ async fn cached_stat_match_skips_read() {+ // Two files. First commit reads both. Second commit, with+ // identical (size, mtime_ns), reads NEITHER — Fast Path 1 hits.+ // mtimes are well in the past (year 2001 / 2004) so they predate the+ // real index file's save time → not racy → Fast Path 1 is trusted.+ let (_dir, vfs, _idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"hello", 1_000_000_000_000_000_000);+ vfs.put("b.md", b"world", 1_100_000_000_000_000_000);++ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_first = vfs.reads();+ assert_eq!(reads_after_first, 2, "first commit must read both files");++ // Second commit, no changes → Noop, but commit() still walks+ // candidates and decides whether to read each. Fast Path 1 means+ // (size, mtime_ns) match → no read needed.+ let resp = svc.commit(req("acct", "main", None)).await.unwrap();+ match resp {+ CommitResponse::Noop { .. } => {}+ other => panic!("expected Noop, got {other:?}"),+ }+ assert_eq!(+ vfs.reads(),+ reads_after_first,+ "Fast Path 1 hit: no extra reads on second commit",+ );+ }++ #[tokio::test]+ async fn racy_clean_same_size_same_mtime_is_not_lost() {+ // Regression for the "racy clean" data-loss bug: a file changed to the+ // same byte length within the same filesystem clock tick as the index+ // write must NOT be skipped by Fast Path 1.+ //+ // We simulate "the file's mtime is in (or after) the index's clock+ // tick" by giving the working-tree file a mtime in the far future+ // (year 2033), which is guaranteed to be >= the real index file's+ // save time. Both versions are 2 bytes with the SAME (size, mtime),+ // exactly the signature Fast Path 1 keys on.+ let racy_mtime = 2_000_000_000_000_000_000; // ~year 2033, >= index save time+ let (_dir, vfs, _idx, svc) = make_service_with_index("acct");++ vfs.put("a.md", b"v1", racy_mtime);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_v1 = vfs.reads();++ // Change content to a different 2-byte value, keeping (size, mtime)+ // identical — the pathological case the stat signature cannot detect.+ vfs.put("a.md", b"v2", racy_mtime);+ let resp = svc.commit(req("acct", "main", None)).await.unwrap();++ // The racy-clean guard must force a slow-path read and capture the+ // change as a real commit. Without the guard this would be a Noop+ // (Fast Path 1 reusing v1's blob oid) — silently dropping v2.+ match resp {+ CommitResponse::Created { .. } => {}+ other => panic!("expected Created (v2 must be committed), got {other:?}"),+ }+ assert_eq!(+ vfs.reads(),+ reads_after_v1 + 1,+ "racy entry (mtime >= index save time) must be re-read, not trusted",+ );++ // And the committed blob must actually be v2, not the stale v1.+ let shown = svc+ .show(ShowRequest {+ account: "acct".to_string(),+ target_ref: "main".to_string(),+ path: Some("a.md".to_string()),+ })+ .await+ .unwrap();+ match shown {+ ShowResponse::Blob { bytes, .. } => {+ assert_eq!(&bytes[..], b"v2", "committed blob must reflect v2, not v1");+ }+ other => panic!("expected Blob, got {other:?}"),+ }+ }++ #[tokio::test]+ async fn size_mismatch_invalidates_cache_entry() {+ let (_dir, vfs, _idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"hello", 1_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_first = vfs.reads();++ // Same mtime, different size → Fast Path 1 must MISS for this file.+ vfs.put("a.md", b"helloX", 1_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ assert_eq!(+ vfs.reads(),+ reads_after_first + 1,+ "size mismatch must trigger one extra read",+ );+ }++ #[tokio::test]+ async fn mtime_mismatch_invalidates_cache_entry() {+ let (_dir, vfs, _idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"hello", 1_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_first = vfs.reads();++ // Same size, different mtime → cache miss.+ vfs.put("a.md", b"hello", 2_000_000_000_000_000_000);+ let resp = svc.commit(req("acct", "main", None)).await.unwrap();+ // Same content → identical oid → no editor change → Noop.+ match resp {+ CommitResponse::Noop { .. } => {}+ other => panic!("expected Noop, got {other:?}"),+ }+ assert_eq!(+ vfs.reads(),+ reads_after_first + 1,+ "mtime mismatch must trigger one extra read",+ );+ }++ #[tokio::test]+ async fn parent_oid_mismatch_disables_cache() {+ // Build a service whose index file's parent_oid is stale relative+ // to the branch HEAD: drop in a hand-crafted CommitIndex pointing at+ // a bogus parent, then commit and assert ALL files were re-read.+ let (dir, vfs, idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"hello", 1_000_000_000_000_000_000);+ vfs.put("b.md", b"world", 2_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_first = vfs.reads();++ // Overwrite the index on disk with one whose parent_oid is bogus.+ let bogus = ObjectId::from_hex(b"deadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap();+ let stale = CommitIndex {+ parent_oid: bogus,+ entries: HashMap::new(), // doesn't matter; whole file is rejected+ saved_at_ns: None,+ };+ idx.save("acct", "main", &stale).await.unwrap();+ let _ = dir; // keep tempdir alive++ // Re-commit with same contents. Cache parent_oid != HEAD → cache+ // discarded entirely → both files re-read.+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ assert_eq!(+ vfs.reads(),+ reads_after_first + 2,+ "parent_oid mismatch must force read of every candidate",+ );+ }++ #[tokio::test]+ async fn deleted_path_is_removed_from_index() {+ let (_dir, vfs, idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"a", 1_000_000_000_000_000_000);+ vfs.put("b.md", b"b", 2_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();++ // Delete a.md, commit with explicit paths so the deletion is+ // observed. Commit succeeds; the persisted index must drop a.md+ // and keep b.md.+ vfs.delete("a.md");+ let _ = svc+ .commit(req(+ "acct",+ "main",+ Some(vec!["a.md".into(), "b.md".into()]),+ ))+ .await+ .unwrap();++ let saved = idx.load("acct", "main").await.unwrap().unwrap();+ assert!(+ !saved.entries.contains_key("a.md"),+ "deleted path must be removed from the index",+ );+ assert!(+ saved.entries.contains_key("b.md"),+ "surviving path must remain in the index",+ );+ }++ #[tokio::test]+ async fn corrupted_index_falls_back_silently() {+ // Drop a malformed file at the index path BEFORE the first commit,+ // then commit normally. The corrupt file makes load() return None,+ // so commit takes the slow path — but it MUST still succeed and+ // overwrite the corrupt file with a valid one.+ let (dir, vfs, idx, svc) = make_service_with_index("acct");+ let path = dir.path().join("acct").join("index").join("main.json");+ tokio::fs::create_dir_all(path.parent().unwrap())+ .await+ .unwrap();+ tokio::fs::write(&path, b"NOT-JSON-AT-ALL").await.unwrap();++ vfs.put("a.md", b"hi", 1_000_000_000_000_000_000);+ let resp = svc.commit(req("acct", "main", None)).await.unwrap();+ assert!(matches!(resp, CommitResponse::Created { .. }));+ // The save after commit succeeded → load now returns a real index.+ let loaded = idx.load("acct", "main").await.unwrap().unwrap();+ assert!(loaded.entries.contains_key("a.md"));+ }++ #[tokio::test]+ async fn partial_paths_preserves_uncovered_entries() {+ // First commit covers a + b.+ // Second commit lists ONLY [a]; b is never enumerated. The new+ // index must still contain b's entry so a future full-enum commit+ // can still hit the cache for b.+ let (_dir, vfs, idx, svc) = make_service_with_index("acct");+ vfs.put("a.md", b"a", 1_000_000_000_000_000_000);+ vfs.put("b.md", b"b", 2_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();++ // Touch a (mtime change) — partial commit on a.md alone.+ vfs.put("a.md", b"a", 3_000_000_000_000_000_000);+ let _ = svc+ .commit(req("acct", "main", Some(vec!["a.md".into()])))+ .await+ .unwrap();++ let saved = idx.load("acct", "main").await.unwrap().unwrap();+ let a = saved+ .entries+ .get("a.md")+ .expect("a.md must be in the index");+ let b = saved.entries.get("b.md").expect(+ "b.md was uncovered by paths=[a.md] but must be preserved \+ from the previous index",+ );+ assert_eq!(a.mtime_ns, 3_000_000_000_000_000_000);+ assert_eq!(b.mtime_ns, 2_000_000_000_000_000_000);+ }++ #[tokio::test]+ async fn no_index_store_disables_fast_path() {+ // Sanity: with index_store=None the slow path runs every commit;+ // a noop second commit still reads every file.+ let (_dir, vfs, svc) = make_service_no_index("acct");+ vfs.put("a.md", b"hi", 1_000_000_000_000_000_000);+ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ let reads_after_first = vfs.reads();++ let _ = svc.commit(req("acct", "main", None)).await.unwrap();+ assert_eq!(+ vfs.reads(),+ reads_after_first + 1,+ "without an IndexStore the slow path runs every commit",+ );+ }++ /// Partial commit with a directory entry must purge `new_index_entries`+ /// by prefix — otherwise a file deleted under that directory leaves a+ /// stale row in the persisted commit index, which the *next* commit+ /// might serve to fast-path 1 as a valid cached oid.+ ///+ /// Uses `LocalFileSystem` because the Directory branch of Step 2.5+ /// only runs when `stat` returns `is_dir = true`. `CountingVfs::stat`+ /// returns NotFound for any directory and so would route this test+ /// through the NotFound branch — which has different prefix-cleanup+ /// behavior (NotFound also clears the exact key).+ #[tokio::test]+ async fn partial_commit_with_directory_path_purges_index_by_prefix() {+ use crate::git::object_store::ObjectStore;+ use crate::git::ref_store::RefStore;+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));+ let index_store = Arc::new(LocalIndexStore::new(store_dir.path()));++ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct");+ std::fs::create_dir_all(acct_root.join("docs")).unwrap();+ std::fs::create_dir_all(acct_root.join("other")).unwrap();+ std::fs::write(acct_root.join("docs/a.md"), b"AA").unwrap();+ std::fs::write(acct_root.join("docs/b.md"), b"BB").unwrap();+ std::fs::write(acct_root.join("other/c.md"), b"CC").unwrap();++ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());+ let svc = GitService::with_index(+ vfs,+ object_store as Arc<dyn ObjectStore>,+ ref_store as Arc<dyn RefStore>,+ Some(index_store.clone() as Arc<dyn IndexStore>),+ );++ let full = CommitRequest {+ account: "acct".into(),+ branch: "main".into(),+ message: "m".into(),+ paths: None,+ author_name: "tester".into(),+ author_email: "t@x".into(),+ };+ let _ = svc.commit(full).await.unwrap();+ let loaded = index_store.load("acct", "main").await.unwrap().unwrap();+ assert!(loaded.entries.contains_key("docs/a.md"));+ assert!(loaded.entries.contains_key("docs/b.md"));+ assert!(loaded.entries.contains_key("other/c.md"));++ // Delete docs/b.md, partial-commit with paths=["docs"].+ std::fs::remove_file(acct_root.join("docs/b.md")).unwrap();+ let partial = CommitRequest {+ account: "acct".into(),+ branch: "main".into(),+ message: "m".into(),+ paths: Some(vec!["docs".into()]),+ author_name: "tester".into(),+ author_email: "t@x".into(),+ };+ let _ = svc.commit(partial).await.unwrap();++ let loaded = index_store.load("acct", "main").await.unwrap().unwrap();+ assert!(+ !loaded.entries.contains_key("docs/b.md"),+ "stale entry for deleted docs/b.md must not survive prefix cleanup"+ );+ assert!(+ loaded.entries.contains_key("docs/a.md"),+ "surviving file under docs/ must have a fresh entry"+ );+ assert!(+ loaded.entries.contains_key("other/c.md"),+ "files outside the partial scope must be preserved verbatim"+ );+ }+}diff --git a/crates/ragfs/src/git/tree_builder.rs b/crates/ragfs/src/git/tree_builder.rsnew file mode 100644index 000000000..34e66b8de--- /dev/null+++ b/crates/ragfs/src/git/tree_builder.rs@@ -0,0 +1,1360 @@+//! Async-native Git tree editor for building and modifying tree objects.++use std::collections::{BTreeMap, HashMap};++use gix_hash::ObjectId;+use gix_object::bstr::{BString, ByteSlice};+use gix_object::tree::{self, EntryKind};+use gix_object::{Tree, TreeRef, WriteTo};++use crate::git::error::GitError;+use crate::git::object_store::ObjectStore;+use crate::git::util::{parse_object_header, read_object, write_object};++/// Type alias for tree entries mapping path components to tree entries+pub type TreeEntries = BTreeMap<BString, tree::Entry>;++/// Editor for constructing and modifying Git tree objects+pub struct TreeEditor {+ pub(crate) root: TreeEntries,+ pub(crate) subtrees: HashMap<BString, TreeEntries>,+}++impl TreeEditor {+ /// Create a new empty TreeEditor+ pub fn empty() -> Self {+ Self {+ root: BTreeMap::new(),+ subtrees: HashMap::new(),+ }+ }++ /// Split a path into components, validating each component.+ fn split_path(path: &str) -> Result<Vec<&str>, GitError> {+ if path.is_empty() {+ return Err(GitError::Other("empty path".into()));+ }++ let components: Vec<&str> = path.split('/').collect();+ for comp in &components {+ if comp.is_empty() {+ return Err(GitError::Other("empty path component".into()));+ }+ }+ Ok(components)+ }++ /// Join path components into a `dir1/dir2/...` BString key.+ fn join_prefix(parts: &[&str]) -> BString {+ let mut out = BString::default();+ for (i, p) in parts.iter().enumerate() {+ if i > 0 {+ out.push(b'/');+ }+ out.extend_from_slice(p.as_bytes());+ }+ out+ }++ /// Ensure every subtree along `parent_dirs` is loaded into `self.subtrees`.+ ///+ /// Walks top-down. For each level not yet present in `self.subtrees`, it+ /// reads the directory entry from the parent level and lazily loads the+ /// referenced tree object (Fast Path 2: untouched subtrees are never+ /// loaded). Returns `Ok(false)` if a component is missing and+ /// `create_missing` is false (used by `remove` for its no-op semantics);+ /// `Ok(true)` once all levels are present.+ async fn ensure_path_loaded(+ &mut self,+ store: &dyn ObjectStore,+ account: &str,+ parent_dirs: &[&str],+ create_missing: bool,+ ) -> Result<bool, GitError> {+ for depth in 1..=parent_dirs.len() {+ let dir_name = parent_dirs[depth - 1];+ let child_key = Self::join_prefix(&parent_dirs[..depth]);++ if self.subtrees.contains_key(&child_key) {+ continue;+ }++ // Inspect the directory entry in the parent level. Copy out the oid+ // (or the decision) before any await to avoid holding a borrow of+ // `self.subtrees`/`self.root` across the load.+ enum Action {+ Load(ObjectId),+ Empty,+ Missing,+ }+ let action = {+ let parent: &TreeEntries = if depth == 1 {+ &self.root+ } else {+ let parent_key = Self::join_prefix(&parent_dirs[..depth - 1]);+ self.subtrees.get(&parent_key).ok_or_else(|| {+ GitError::Other(format!("subtree not loaded: {parent_key}"))+ })?+ };+ match parent.get(dir_name.as_bytes().as_bstr()) {+ // Existing directory entry: either an empty subtree or one+ // to load. Null and the well-known empty-tree oid are both+ // treated as empty — the empty tree object is conventionally+ // never physically stored, so we must not try to load it.+ Some(entry) if entry.mode == EntryKind::Tree.into() => {+ if entry.oid.is_null()+ || entry.oid == ObjectId::empty_tree(gix_hash::Kind::Sha1)+ {+ Action::Empty+ } else {+ Action::Load(entry.oid)+ }+ }+ // Either no entry, or one that exists but is a file/symlink+ // (a file→dir transition). Treat both as missing: the create+ // path overwrites the stale opposite-kind entry with a fresh+ // directory; the no-create path (remove) no-ops.+ _ => Action::Missing,+ }+ };++ match action {+ Action::Load(oid) => {+ let entries = load_tree_entries(store, account, &oid).await?;+ self.subtrees.insert(child_key, entries);+ }+ Action::Empty => {+ self.subtrees.insert(child_key, BTreeMap::new());+ }+ Action::Missing => {+ if !create_missing {+ return Ok(false);+ }+ // Create the directory entry in the parent level, then an+ // empty subtree for it.+ let parent: &mut TreeEntries = if depth == 1 {+ &mut self.root+ } else {+ let parent_key = Self::join_prefix(&parent_dirs[..depth - 1]);+ self.subtrees.entry(parent_key).or_insert_with(BTreeMap::new)+ };+ parent.insert(+ dir_name.into(),+ tree::Entry {+ mode: EntryKind::Tree.into(),+ filename: dir_name.into(),+ oid: ObjectId::null(gix_hash::Kind::Sha1),+ },+ );+ self.subtrees.insert(child_key, BTreeMap::new());+ }+ }+ }+ Ok(true)+ }++ /// Upsert a blob object at the given path.+ pub async fn upsert(+ &mut self,+ store: &dyn ObjectStore,+ account: &str,+ path: &str,+ oid: ObjectId,+ ) -> Result<(), GitError> {+ let components = Self::split_path(path)?;+ let (filename, parent_dirs) = components+ .split_last()+ .ok_or_else(|| GitError::Other("empty path".into()))?;++ let leaf = tree::Entry {+ mode: EntryKind::Blob.into(),+ filename: (*filename).into(),+ oid,+ };++ if parent_dirs.is_empty() {+ self.root.insert((*filename).into(), leaf);+ return Ok(());+ }++ self.ensure_path_loaded(store, account, parent_dirs, true)+ .await?;++ let leaf_key = Self::join_prefix(parent_dirs);+ let subtree = self.subtrees.entry(leaf_key).or_insert_with(BTreeMap::new);+ subtree.insert((*filename).into(), leaf);++ Ok(())+ }++ /// Remove a path from the tree. No-op if the path does not exist.+ pub async fn remove(+ &mut self,+ store: &dyn ObjectStore,+ account: &str,+ path: &str,+ ) -> Result<(), GitError> {+ let components = Self::split_path(path)?;+ let (filename, parent_dirs) = components+ .split_last()+ .ok_or_else(|| GitError::Other("empty path".into()))?;++ if parent_dirs.is_empty() {+ self.root.remove(filename.as_bytes().as_bstr());+ return Ok(());+ }++ // Missing ancestor → nothing to remove (keep no-op semantics, do not+ // create directories).+ if !self+ .ensure_path_loaded(store, account, parent_dirs, false)+ .await?+ {+ return Ok(());+ }++ let prefix = Self::join_prefix(parent_dirs);+ if let Some(subtree) = self.subtrees.get_mut(&prefix) {+ subtree.remove(filename.as_bytes().as_bstr());+ }+ Ok(())+ }++ /// Splice an existing subtree (referenced by its OID) into the editor at the+ /// given path. The path's intermediate ancestors are created as needed.+ ///+ /// Any in-memory editor state under `path` is discarded — subsequent+ /// `write()` calls will reference `subtree_oid` directly without rebuilding+ /// the subtree. This is the API `restore` uses to swap a whole project+ /// directory to a historical version without enumerating every file.+ ///+ /// Note: if you later call `upsert`/`remove` *inside* the spliced subtree+ /// (e.g. `upsert_subtree("a/b", oid); upsert("a/b/x.txt", ...)`), the+ /// in-memory state for "a/b" is rebuilt from those edits alone — the+ /// contents of `subtree_oid` are not merged in. Splice, then edit, is a+ /// destructive pattern.+ pub async fn upsert_subtree(+ &mut self,+ store: &dyn ObjectStore,+ account: &str,+ path: &str,+ subtree_oid: ObjectId,+ ) -> Result<(), GitError> {+ let components = Self::split_path(path)?;+ let (dirname, parent_dirs) = components+ .split_last()+ .ok_or_else(|| GitError::Other("empty path".into()))?;++ // Ensure each ancestor directory's subtree is loaded (so sibling+ // entries are preserved), creating missing ancestors as needed.+ self.ensure_path_loaded(store, account, parent_dirs, true)+ .await?;++ // Insert the leaf Tree entry pointing at the precomputed subtree.+ let leaf_entry = tree::Entry {+ mode: EntryKind::Tree.into(),+ filename: (*dirname).into(),+ oid: subtree_oid,+ };+ let leaf_parent: &mut TreeEntries = if parent_dirs.is_empty() {+ &mut self.root+ } else {+ let key = Self::join_prefix(parent_dirs);+ self.subtrees.entry(key).or_insert_with(BTreeMap::new)+ };+ leaf_parent.insert((*dirname).into(), leaf_entry);++ // Drop any stale in-memory state at or beneath `path` so write_subtree+ // doesn't recurse — it will reuse `subtree_oid` directly.+ let prefix = Self::join_prefix(&components);+ let prefix_slash: Vec<u8> = {+ let mut v = Vec::with_capacity(prefix.len() + 1);+ v.extend_from_slice(prefix.as_slice());+ v.push(b'/');+ v+ };+ let to_remove: Vec<BString> = self+ .subtrees+ .keys()+ .filter(|k| {+ k.as_slice() == prefix.as_slice()+ || k.as_slice().starts_with(&prefix_slash)+ })+ .cloned()+ .collect();+ for k in to_remove {+ self.subtrees.remove(&k);+ }++ Ok(())+ }++ /// Load an existing tree from ObjectStore as the editing base.+ ///+ /// Only the root tree is loaded eagerly; subtrees are loaded lazily on+ /// first `upsert`/`remove`/`upsert_subtree` that touches them. Untouched+ /// subtrees are never read into memory and are reused as-is during+ /// `write` (Fast Path 2).+ pub async fn from_tree(+ store: &dyn ObjectStore,+ account: &str,+ tree_oid: ObjectId,+ ) -> Result<Self, GitError> {+ let mut editor = Self::empty();+ editor.root = load_tree_entries(store, account, &tree_oid).await?;+ Ok(editor)+ }++ /// Write all in-memory trees to ObjectStore, returning the root tree oid.+ /// Writes bottom-up: leaf subtrees first, then their parents.+ /// Empty subtrees are pruned.+ pub async fn write(+ &mut self,+ store: &dyn ObjectStore,+ account: &str,+ ) -> Result<ObjectId, GitError> {+ self.write_subtree(store, account, &BString::default()).await+ }++ fn write_subtree<'a>(+ &'a mut self,+ store: &'a dyn ObjectStore,+ account: &'a str,+ prefix: &'a BString,+ ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<ObjectId, GitError>> + Send + 'a>>+ {+ Box::pin(async move {+ // Snapshot entry keys so we can mutate self.subtrees during recursion.+ let entry_specs: Vec<(BString, tree::Entry)> = {+ let entries = if prefix.is_empty() {+ &self.root+ } else {+ self.subtrees.get(prefix).ok_or_else(|| {+ GitError::Other(format!("subtree not found: {prefix}"))+ })?+ };+ entries.iter().map(|(k, v)| (k.clone(), v.clone())).collect()+ };++ let mut result_entries: Vec<tree::Entry> = Vec::with_capacity(entry_specs.len());+ for (name, entry) in entry_specs {+ if entry.mode.is_tree() {+ let child_prefix = if prefix.is_empty() {+ name.clone()+ } else {+ let mut p = prefix.clone();+ p.push(b'/');+ p.extend_from_slice(&name);+ p+ };++ match self.subtrees.get(&child_prefix) {+ Some(child_entries) if child_entries.is_empty() => {+ // Prune empty subtree.+ continue;+ }+ Some(_) => {+ // Subtree has in-memory edits — recurse to write them.+ let child_oid = self.write_subtree(store, account, &child_prefix).await?;+ result_entries.push(tree::Entry {+ mode: EntryKind::Tree.into(),+ filename: name,+ oid: child_oid,+ });+ }+ None => {+ // No in-memory state: use the entry's existing OID as-is+ // (e.g. placed by upsert_subtree or from_tree for untouched+ // subtrees). This is the Fast Path 2 optimisation.+ result_entries.push(entry);+ }+ }+ } else {+ result_entries.push(entry);+ }+ }++ result_entries.sort();+ let tree = Tree { entries: result_entries };+ let mut buf = Vec::new();+ tree.write_to(&mut buf)+ .map_err(|e| GitError::Other(format!("tree serialization: {e}")))?;++ let oid = write_object(store, account, gix_object::Kind::Tree, &buf).await?;+ Ok(oid)+ })+ }+}++/// Convert BTreeMap entries to a `gix_object::Tree` with Git sort order.+#[cfg(test)]+fn entries_to_tree(entries: &TreeEntries) -> Tree {+ let mut sorted: Vec<tree::Entry> = entries.values().cloned().collect();+ sorted.sort();+ Tree { entries: sorted }+}++/// Read and parse a tree object from ObjectStore.+async fn load_tree(+ store: &dyn ObjectStore,+ account: &str,+ oid: &ObjectId,+) -> Result<Tree, GitError> {+ let raw = read_object(store, account, oid).await?;+ let (_, _, header_len) = parse_object_header(&raw)?;+ let tree_ref = TreeRef::from_bytes(&raw[header_len..])+ .map_err(|e| GitError::CorruptedObject(format!("invalid tree: {e}")))?;+ Ok(Tree::from(tree_ref))+}++/// Load a tree object and convert it into a `TreeEntries` map keyed by filename.+async fn load_tree_entries(+ store: &dyn ObjectStore,+ account: &str,+ oid: &ObjectId,+) -> Result<TreeEntries, GitError> {+ let tree = load_tree(store, account, oid).await?;+ let mut entries = BTreeMap::new();+ for entry in tree.entries {+ entries.insert(entry.filename.clone(), entry);+ }+ Ok(entries)+}++/// Recursively flatten a tree into (path, blob_oid) pairs.+///+/// If `path_filter` is Some, only include blob paths whose prefix matches+/// any of the filter prefixes. Subtrees are descended into only when relevant.+pub async fn flatten(+ store: &dyn ObjectStore,+ account: &str,+ tree_oid: ObjectId,+ path_filter: &Option<Vec<String>>,+) -> Result<Vec<(String, ObjectId)>, GitError> {+ let mut result = Vec::new();+ let mut stack: Vec<(String, ObjectId)> = vec![(String::new(), tree_oid)];++ while let Some((prefix, oid)) = stack.pop() {+ let tree = load_tree(store, account, &oid).await?;+ for entry in tree.entries {+ let path = if prefix.is_empty() {+ entry.filename.to_string()+ } else {+ format!("{}/{}", prefix, entry.filename)+ };++ if entry.mode.is_tree() {+ let should_descend = match path_filter {+ None => true,+ Some(filters) => filters+ .iter()+ .any(|f| path.starts_with(f) || f.starts_with(&path)),+ };+ if should_descend {+ stack.push((path, entry.oid));+ }+ } else {+ let include = match path_filter {+ None => true,+ Some(filters) => filters.iter().any(|f| path.starts_with(f)),+ };+ if include {+ result.push((path, entry.oid));+ }+ }+ }+ }++ result.sort_by(|a, b| a.0.cmp(&b.0));+ Ok(result)+}++/// Look up a single path in a tree, returning the entry's oid and mode.+/// Returns `Ok(None)` if the path doesn't exist.+pub async fn lookup(+ store: &dyn ObjectStore,+ account: &str,+ tree_oid: ObjectId,+ path: &str,+) -> Result<Option<(ObjectId, tree::EntryMode)>, GitError> {+ let mut cache = TreeLookupCache::new();+ lookup_cached(store, account, tree_oid, path, &mut cache).await+}++/// In-memory cache of decoded tree objects keyed by their OID. Intended for use+/// across many `lookup_cached` calls that share the same root (e.g. the commit+/// hot loop, where K candidate paths each walk depth-D ancestor trees that+/// otherwise get re-fetched + re-zlib-decoded K×D times).+///+/// Entries are `Arc`-shared so a clone is cheap; the cache is single-writer+/// (the caller's `&mut`) so no internal locking is needed.+pub struct TreeLookupCache {+ by_oid: HashMap<ObjectId, std::sync::Arc<TreeEntries>>,+}++impl TreeLookupCache {+ /// Create an empty cache.+ pub fn new() -> Self {+ Self {+ by_oid: HashMap::new(),+ }+ }++ /// Pre-seed the cache with an already-decoded tree's entries. Useful when+ /// the caller has the root entries on hand (e.g. from `TreeEditor::from_tree`)+ /// and wants the very first `lookup_cached` to skip the redundant fetch.+ pub fn seed(&mut self, oid: ObjectId, entries: TreeEntries) {+ self.by_oid.insert(oid, std::sync::Arc::new(entries));+ }+}++impl Default for TreeLookupCache {+ fn default() -> Self {+ Self::new()+ }+}++/// Same as [`lookup`], but reuses an external [`TreeLookupCache`] across calls+/// so each tree object is fetched + decoded at most once. The cache is keyed+/// on the *content-addressed* tree OID, so it stays correct across calls with+/// different starting roots.+pub async fn lookup_cached(+ store: &dyn ObjectStore,+ account: &str,+ tree_oid: ObjectId,+ path: &str,+ cache: &mut TreeLookupCache,+) -> Result<Option<(ObjectId, tree::EntryMode)>, GitError> {+ if path.is_empty() {+ return Err(GitError::Other("empty path".into()));+ }+ let components: Vec<&str> = path.split('/').collect();+ let mut current_oid = tree_oid;++ for (i, component) in components.iter().enumerate() {+ if component.is_empty() {+ return Err(GitError::Other("empty path component".into()));+ }+ let entries = match cache.by_oid.get(¤t_oid) {+ Some(e) => e.clone(),+ None => {+ let loaded = std::sync::Arc::new(+ load_tree_entries(store, account, ¤t_oid).await?,+ );+ cache.by_oid.insert(current_oid, loaded.clone());+ loaded+ }+ };+ let filename = component.as_bytes();+ let is_last = i == components.len() - 1;++ match entries.get(filename.as_bstr()) {+ Some(entry) => {+ if is_last {+ return Ok(Some((entry.oid, entry.mode)));+ } else if entry.mode.is_tree() {+ current_oid = entry.oid;+ } else {+ return Ok(None);+ }+ }+ None => return Ok(None),+ }+ }++ Ok(None)+}++#[cfg(test)]+mod tests {+ use super::*;++ fn dummy_oid() -> ObjectId {+ ObjectId::null(gix_hash::Kind::Sha1)+ }++ #[test]+ fn test_empty_editor() {+ let editor = TreeEditor::empty();+ assert!(editor.root.is_empty());+ assert!(editor.subtrees.is_empty());+ }++ #[tokio::test]+ async fn test_upsert_single_file() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ editor.upsert(&store, "acc", "file.txt", oid).await.unwrap();++ assert_eq!(editor.root.len(), 1);+ let entry = editor.root.get("file.txt".as_bytes().as_bstr()).unwrap();+ assert_eq!(entry.mode, EntryKind::Blob.into());+ assert_eq!(entry.oid, oid);+ assert_eq!(entry.filename, "file.txt");+ }++ #[tokio::test]+ async fn test_upsert_nested_path() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ editor+ .upsert(&store, "acc", "dir/subdir/file.txt", oid)+ .await+ .unwrap();++ // Root has dir+ assert_eq!(editor.root.len(), 1);+ let dir_entry = editor.root.get("dir".as_bytes().as_bstr()).unwrap();+ assert_eq!(dir_entry.mode, EntryKind::Tree.into());++ // Subtrees has dir+ let dir_subtree = editor.subtrees.get("dir".as_bytes().as_bstr()).unwrap();+ assert_eq!(dir_subtree.len(), 1);+ let subdir_entry = dir_subtree.get("subdir".as_bytes().as_bstr()).unwrap();+ assert_eq!(subdir_entry.mode, EntryKind::Tree.into());++ // Subdir subtree+ let subdir_subtree = editor.subtrees.get("dir/subdir".as_bytes().as_bstr()).unwrap();+ assert_eq!(subdir_subtree.len(), 1);+ let file_entry = subdir_subtree.get("file.txt".as_bytes().as_bstr()).unwrap();+ assert_eq!(file_entry.mode, EntryKind::Blob.into());+ assert_eq!(file_entry.oid, oid);+ }++ #[tokio::test]+ async fn test_upsert_overwrite() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid1 = dummy_oid();+ let oid2 = ObjectId::from_hex(b"abcdef1234567890abcdef1234567890abcdef12").unwrap();++ editor.upsert(&store, "acc", "file.txt", oid1).await.unwrap();+ editor.upsert(&store, "acc", "file.txt", oid2).await.unwrap();++ let entry = editor.root.get("file.txt".as_bytes().as_bstr()).unwrap();+ assert_eq!(entry.oid, oid2);+ }++ #[tokio::test]+ async fn test_upsert_empty_component_rejected() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ assert!(editor.upsert(&store, "acc", "", oid).await.is_err());+ assert!(editor.upsert(&store, "acc", "file//txt", oid).await.is_err());+ assert!(editor.upsert(&store, "acc", "/file.txt", oid).await.is_err());+ assert!(editor.upsert(&store, "acc", "file.txt/", oid).await.is_err());+ }++ #[tokio::test]+ async fn test_remove_existing() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ editor.upsert(&store, "acc", "dir/file.txt", oid).await.unwrap();+ assert_eq!(editor.root.len(), 1);++ editor.remove(&store, "acc", "dir/file.txt").await.unwrap();++ let dir_subtree = editor.subtrees.get("dir".as_bytes().as_bstr()).unwrap();+ assert!(dir_subtree.is_empty());+ }++ #[tokio::test]+ async fn test_remove_nonexistent_is_noop() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ editor.remove(&store, "acc", "nonexistent.txt").await.unwrap();+ editor.remove(&store, "acc", "dir/nonexistent.txt").await.unwrap();+ }++ #[tokio::test]+ async fn test_upsert_top_level_file() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ editor.upsert(&store, "acc", "top-level.txt", oid).await.unwrap();++ assert_eq!(editor.root.len(), 1);+ let entry = editor.root.get("top-level.txt".as_bytes().as_bstr()).unwrap();+ assert_eq!(entry.mode, EntryKind::Blob.into());+ assert_eq!(entry.filename, "top-level.txt");+ assert_eq!(entry.oid, oid);+ }++ #[tokio::test]+ async fn test_remove_top_level_file() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = dummy_oid();++ editor.upsert(&store, "acc", "single.txt", oid).await.unwrap();+ assert_eq!(editor.root.len(), 1);++ editor.remove(&store, "acc", "single.txt").await.unwrap();+ assert_eq!(editor.root.len(), 0);+ }++ // --- Test helpers ---++ fn make_store() -> (tempfile::TempDir, crate::git::backends::local::LocalObjectStore) {+ let dir = tempfile::tempdir().unwrap();+ let store = crate::git::backends::local::LocalObjectStore::new(dir.path());+ (dir, store)+ }++ fn serialize_tree(tree: &Tree) -> Vec<u8> {+ let mut buf = Vec::new();+ tree.write_to(&mut buf).unwrap();+ buf+ }++ fn oid_hex(hex: &[u8; 40]) -> ObjectId {+ ObjectId::from_hex(hex).unwrap()+ }++ // --- from_tree ---++ #[tokio::test]+ async fn test_from_tree_empty() {+ let (_d, store) = make_store();+ let empty_tree = Tree { entries: Vec::new() };+ let oid = write_object(&store, "acc", gix_object::Kind::Tree, &serialize_tree(&empty_tree))+ .await+ .unwrap();++ let editor = TreeEditor::from_tree(&store, "acc", oid).await.unwrap();+ assert!(editor.root.is_empty());+ assert!(editor.subtrees.is_empty());+ }++ #[tokio::test]+ async fn test_from_tree_with_entries() {+ let (_d, store) = make_store();++ let blob_a = oid_hex(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");+ let blob_b = oid_hex(b"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");++ let resources_tree = Tree {+ entries: vec![tree::Entry {+ mode: EntryKind::Blob.into(),+ filename: "b.md".into(),+ oid: blob_b,+ }],+ };+ let resources_oid = write_object(&store, "acc", gix_object::Kind::Tree, &serialize_tree(&resources_tree))+ .await+ .unwrap();++ let root_tree = Tree {+ entries: vec![+ tree::Entry {+ mode: EntryKind::Blob.into(),+ filename: "a.md".into(),+ oid: blob_a,+ },+ tree::Entry {+ mode: EntryKind::Tree.into(),+ filename: "resources".into(),+ oid: resources_oid,+ },+ ],+ };+ let root_oid = write_object(&store, "acc", gix_object::Kind::Tree, &serialize_tree(&root_tree))+ .await+ .unwrap();++ let editor = TreeEditor::from_tree(&store, "acc", root_oid).await.unwrap();+ assert_eq!(editor.root.len(), 2);+ assert!(editor.root.contains_key("a.md".as_bytes().as_bstr()));+ assert!(editor.root.contains_key("resources".as_bytes().as_bstr()));++ // Lazy loading: from_tree only loads root; subtrees are not read yet.+ assert!(editor.subtrees.is_empty());+ }++ // --- write ---++ #[tokio::test]+ async fn test_write_empty_tree() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let oid = editor.write(&store, "acc").await.unwrap();+ assert_eq!(oid, ObjectId::empty_tree(gix_hash::Kind::Sha1));+ }++ #[tokio::test]+ async fn test_write_single_blob() {+ let (_d, store) = make_store();+ let blob_oid = oid_hex(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "README.md", blob_oid).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let tree = load_tree(&store, "acc", &root_oid).await.unwrap();+ assert_eq!(tree.entries.len(), 1);+ assert_eq!(tree.entries[0].filename, "README.md");+ assert_eq!(tree.entries[0].oid, blob_oid);+ }++ #[tokio::test]+ async fn test_write_nested_structure() {+ let (_d, store) = make_store();+ let oid1 = oid_hex(b"1111111111111111111111111111111111111111");+ let oid2 = oid_hex(b"2222222222222222222222222222222222222222");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "README.md", oid1).await.unwrap();+ editor.upsert(&store, "acc", "resources/docs/a.md", oid2).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let root_tree = load_tree(&store, "acc", &root_oid).await.unwrap();+ assert_eq!(root_tree.entries.len(), 2);++ let resources_entry = root_tree+ .entries+ .iter()+ .find(|e| e.filename == "resources")+ .unwrap();+ assert!(resources_entry.mode.is_tree());++ let res_tree = load_tree(&store, "acc", &resources_entry.oid).await.unwrap();+ assert_eq!(res_tree.entries.len(), 1);++ let docs_entry = &res_tree.entries[0];+ assert!(docs_entry.mode.is_tree());+ let docs_tree = load_tree(&store, "acc", &docs_entry.oid).await.unwrap();+ assert_eq!(docs_tree.entries.len(), 1);+ assert_eq!(docs_tree.entries[0].oid, oid2);+ }++ #[tokio::test]+ async fn test_round_trip_from_tree_upsert_write() {+ let (_d, store) = make_store();+ let oid1 = oid_hex(b"1111111111111111111111111111111111111111");+ let oid2 = oid_hex(b"2222222222222222222222222222222222222222");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "a.md", oid1).await.unwrap();+ let first_oid = editor.write(&store, "acc").await.unwrap();++ let mut editor2 = TreeEditor::from_tree(&store, "acc", first_oid).await.unwrap();+ editor2.upsert(&store, "acc", "b.md", oid2).await.unwrap();+ let second_oid = editor2.write(&store, "acc").await.unwrap();++ let tree = load_tree(&store, "acc", &second_oid).await.unwrap();+ assert_eq!(tree.entries.len(), 2);+ }++ #[tokio::test]+ async fn test_file_to_dir_transition_overwrites_blob() {+ // Prev tree: `foo` is a file (Blob). Then a path appears *under* it+ // (`foo/bar.md`), i.e. `foo` is now a directory. Upsert must replace+ // the stale Blob entry with a Tree and place the child inside it.+ let (_d, store) = make_store();+ let blob_foo = oid_hex(b"1111111111111111111111111111111111111111");+ let blob_bar = oid_hex(b"2222222222222222222222222222222222222222");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "foo", blob_foo).await.unwrap();+ let first_oid = editor.write(&store, "acc").await.unwrap();++ let mut editor2 = TreeEditor::from_tree(&store, "acc", first_oid).await.unwrap();+ editor2+ .upsert(&store, "acc", "foo/bar.md", blob_bar)+ .await+ .unwrap();+ let second_oid = editor2.write(&store, "acc").await.unwrap();++ let root = load_tree(&store, "acc", &second_oid).await.unwrap();+ assert_eq!(root.entries.len(), 1);+ let foo_entry = &root.entries[0];+ assert_eq!(foo_entry.filename, "foo");+ assert!(foo_entry.mode.is_tree(), "foo must now be a directory");++ let foo_tree = load_tree(&store, "acc", &foo_entry.oid).await.unwrap();+ assert_eq!(foo_tree.entries.len(), 1);+ assert_eq!(foo_tree.entries[0].filename, "bar.md");+ assert_eq!(foo_tree.entries[0].oid, blob_bar);+ }++ #[tokio::test]+ async fn test_remove_under_file_is_noop() {+ // Prev tree: `foo` is a file. Removing `foo/bar.md` (treating `foo` as+ // a dir) must be a silent no-op — not an error — and leave `foo` intact.+ let (_d, store) = make_store();+ let blob_foo = oid_hex(b"1111111111111111111111111111111111111111");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "foo", blob_foo).await.unwrap();+ let first_oid = editor.write(&store, "acc").await.unwrap();++ let mut editor2 = TreeEditor::from_tree(&store, "acc", first_oid).await.unwrap();+ editor2.remove(&store, "acc", "foo/bar.md").await.unwrap();+ let second_oid = editor2.write(&store, "acc").await.unwrap();++ let root = load_tree(&store, "acc", &second_oid).await.unwrap();+ assert_eq!(root.entries.len(), 1);+ assert_eq!(root.entries[0].filename, "foo");+ assert!(root.entries[0].mode == EntryKind::Blob.into());+ assert_eq!(root.entries[0].oid, blob_foo);+ }++ // --- flatten ---++ #[tokio::test]+ async fn test_flatten_empty_tree() {+ let (_d, store) = make_store();+ let empty_tree = Tree { entries: Vec::new() };+ let oid = write_object(&store, "acc", gix_object::Kind::Tree, &serialize_tree(&empty_tree))+ .await+ .unwrap();+ let result = flatten(&store, "acc", oid, &None).await.unwrap();+ assert!(result.is_empty());+ }++ #[tokio::test]+ async fn test_flatten_nested_tree() {+ let (_d, store) = make_store();+ let oid1 = oid_hex(b"1111111111111111111111111111111111111111");+ let oid2 = oid_hex(b"2222222222222222222222222222222222222222");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "README.md", oid1).await.unwrap();+ editor.upsert(&store, "acc", "resources/docs/a.md", oid2).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let result = flatten(&store, "acc", root_oid, &None).await.unwrap();+ assert_eq!(result.len(), 2);+ assert_eq!(result[0].0, "README.md");+ assert_eq!(result[0].1, oid1);+ assert_eq!(result[1].0, "resources/docs/a.md");+ assert_eq!(result[1].1, oid2);+ }++ #[tokio::test]+ async fn test_flatten_with_path_filter() {+ let (_d, store) = make_store();+ let oid1 = oid_hex(b"1111111111111111111111111111111111111111");+ let oid2 = oid_hex(b"2222222222222222222222222222222222222222");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "a.md", oid1).await.unwrap();+ editor.upsert(&store, "acc", "resources/b.md", oid2).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let filter = Some(vec!["resources".to_string()]);+ let result = flatten(&store, "acc", root_oid, &filter).await.unwrap();+ assert_eq!(result.len(), 1);+ assert_eq!(result[0].0, "resources/b.md");+ assert_eq!(result[0].1, oid2);+ }++ // --- lookup ---++ #[tokio::test]+ async fn test_lookup_blob_in_root() {+ let (_d, store) = make_store();+ let blob_oid = oid_hex(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "README.md", blob_oid).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let (found, mode) = lookup(&store, "acc", root_oid, "README.md")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(found, blob_oid);+ assert!(mode.is_blob());+ }++ #[tokio::test]+ async fn test_lookup_nested_blob() {+ let (_d, store) = make_store();+ let blob_oid = oid_hex(b"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "resources/a.md", blob_oid).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let (found, _) = lookup(&store, "acc", root_oid, "resources/a.md")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(found, blob_oid);+ }++ #[tokio::test]+ async fn test_lookup_not_found() {+ let (_d, store) = make_store();+ let empty_tree = Tree { entries: Vec::new() };+ let root_oid = write_object(&store, "acc", gix_object::Kind::Tree, &serialize_tree(&empty_tree))+ .await+ .unwrap();+ let result = lookup(&store, "acc", root_oid, "nonexistent.md").await.unwrap();+ assert!(result.is_none());+ }++ #[tokio::test]+ async fn test_lookup_tree_entry() {+ let (_d, store) = make_store();+ let blob_oid = oid_hex(b"cccccccccccccccccccccccccccccccccccccccc");+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "resources/a.md", blob_oid).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ let (found, mode) = lookup(&store, "acc", root_oid, "resources")+ .await+ .unwrap()+ .unwrap();+ assert!(mode.is_tree());+ // Verify by loading and confirming it has 1 entry+ let subtree = load_tree(&store, "acc", &found).await.unwrap();+ assert_eq!(subtree.entries.len(), 1);+ assert_eq!(subtree.entries[0].filename, "a.md");+ }++ // --- Sort order ---++ #[test]+ fn test_git_sort_order_preserved() {+ // Git sorts trees as if their name had a trailing '/'.+ // So blob "foo.c" comes before tree "foo" (which sorts as "foo/").+ let oid = dummy_oid();+ let mut entries = BTreeMap::new();+ entries.insert(+ "foo.c".into(),+ tree::Entry {+ mode: EntryKind::Blob.into(),+ filename: "foo.c".into(),+ oid,+ },+ );+ entries.insert(+ "foo".into(),+ tree::Entry {+ mode: EntryKind::Tree.into(),+ filename: "foo".into(),+ oid,+ },+ );++ let git_tree = entries_to_tree(&entries);+ assert_eq!(git_tree.entries[0].filename, "foo.c");+ assert_eq!(git_tree.entries[1].filename, "foo");+ assert!(git_tree.entries[0].mode.is_blob());+ assert!(git_tree.entries[1].mode.is_tree());+ }++ // --- Upsert subtree ---++ #[tokio::test]+ async fn test_upsert_subtree_root_level() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let tree_oid = ObjectId::empty_tree(gix_hash::Kind::Sha1);++ editor.upsert_subtree(&store, "acc", "subdir", tree_oid).await.unwrap();++ assert_eq!(editor.root.len(), 1);+ let entry = editor.root.get("subdir".as_bytes().as_bstr()).unwrap();+ assert!(entry.mode.is_tree());+ assert_eq!(entry.oid, tree_oid);++ // write() should reuse the OID directly (no recursion into self.subtrees)+ let root_oid = editor.write(&store, "acc").await.unwrap();+ let root = load_tree(&store, "acc", &root_oid).await.unwrap();+ assert_eq!(root.entries.len(), 1);+ assert_eq!(root.entries[0].filename, "subdir");+ assert_eq!(root.entries[0].oid, tree_oid);+ }++ #[tokio::test]+ async fn test_upsert_subtree_nested() {+ let (_d, store) = make_store();+ let mut editor = TreeEditor::empty();+ let tree_oid = ObjectId::empty_tree(gix_hash::Kind::Sha1);++ editor.upsert_subtree(&store, "acc", "a/b/c", tree_oid).await.unwrap();++ assert_eq!(editor.root.len(), 1);+ assert!(editor.root.get("a".as_bytes().as_bstr()).unwrap().mode.is_tree());+ assert!(editor.root.get("a".as_bytes().as_bstr()).unwrap().oid.is_null());++ let a_sub = editor.subtrees.get("a".as_bytes().as_bstr()).unwrap();+ assert_eq!(a_sub.len(), 1);+ assert!(a_sub.get("b".as_bytes().as_bstr()).unwrap().mode.is_tree());++ let ab_sub = editor.subtrees.get("a/b".as_bytes().as_bstr()).unwrap();+ assert_eq!(ab_sub.len(), 1);+ assert!(ab_sub.get("c".as_bytes().as_bstr()).unwrap().mode.is_tree());+ assert_eq!(ab_sub.get("c".as_bytes().as_bstr()).unwrap().oid, tree_oid);++ // No in-memory state for "a/b/c" — written directly.+ assert!(editor.subtrees.get("a/b/c".as_bytes().as_bstr()).is_none());++ let root_oid = editor.write(&store, "acc").await.unwrap();+ let root = load_tree(&store, "acc", &root_oid).await.unwrap();+ assert_eq!(root.entries.len(), 1);+ let a_oid = root.entries[0].oid;+ let a_tree = load_tree(&store, "acc", &a_oid).await.unwrap();+ assert_eq!(a_tree.entries.len(), 1);+ assert_eq!(a_tree.entries[0].filename, "b");+ }++ #[tokio::test]+ async fn test_upsert_subtree_clears_existing_state() {+ let (_d, store) = make_store();+ let oid1 = oid_hex(b"1111111111111111111111111111111111111111");+ let oid2 = oid_hex(b"2222222222222222222222222222222222222222");++ // Build editor with a/b/x.txt and a/b/y.txt+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "a/b/x.txt", oid1).await.unwrap();+ editor.upsert(&store, "acc", "a/b/y.txt", oid2).await.unwrap();+ assert!(editor.subtrees.contains_key("a/b".as_bytes().as_bstr()));++ // Replace a/b with an empty subtree+ let empty_tree = ObjectId::empty_tree(gix_hash::Kind::Sha1);+ editor.upsert_subtree(&store, "acc", "a/b", empty_tree).await.unwrap();++ // Stale "a/b" subtree should be gone+ assert!(editor.subtrees.get("a/b".as_bytes().as_bstr()).is_none());++ let root_oid = editor.write(&store, "acc").await.unwrap();+ let root = load_tree(&store, "acc", &root_oid).await.unwrap();+ let b_entry = root.entries.iter().find(|e| e.filename == "a").unwrap();+ let a_tree = load_tree(&store, "acc", &b_entry.oid).await.unwrap();+ assert_eq!(a_tree.entries.len(), 1);+ assert_eq!(a_tree.entries[0].filename, "b");+ assert_eq!(a_tree.entries[0].oid, empty_tree);+ }++ #[tokio::test]+ async fn test_upsert_subtree_then_upsert_inside() {+ let (_d, store) = make_store();+ let oid = oid_hex(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");++ let mut editor = TreeEditor::empty();+ editor.upsert_subtree(&store, "acc", "a/b", ObjectId::empty_tree(gix_hash::Kind::Sha1)).await.unwrap();++ // Upsert inside the spliced subtree creates new in-memory state from scratch.+ editor.upsert(&store, "acc", "a/b/c.txt", oid).await.unwrap();++ let root_oid = editor.write(&store, "acc").await.unwrap();+ let root = load_tree(&store, "acc", &root_oid).await.unwrap();+ let a_entry = root.entries.iter().find(|e| e.filename == "a").unwrap();+ let a_tree = load_tree(&store, "acc", &a_entry.oid).await.unwrap();+ let b_entry = a_tree.entries.iter().find(|e| e.filename == "b").unwrap();+ let b_tree = load_tree(&store, "acc", &b_entry.oid).await.unwrap();+ assert_eq!(b_tree.entries.len(), 1);+ assert_eq!(b_tree.entries[0].filename, "c.txt");+ assert_eq!(b_tree.entries[0].oid, oid);+ }++ // --- Integration ---++ #[tokio::test]+ async fn test_commit_flow_round_trip() {+ let (_d, store) = make_store();+ let oid_readme = oid_hex(b"1111111111111111111111111111111111111111");+ let oid_doc = oid_hex(b"2222222222222222222222222222222222222222");+ let oid_skill = oid_hex(b"3333333333333333333333333333333333333333");++ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "README.md", oid_readme).await.unwrap();+ editor.upsert(&store, "acc", "resources/docs/a.md", oid_doc).await.unwrap();+ editor.upsert(&store, "acc", "agent/skills/b.py", oid_skill).await.unwrap();+ let commit1_oid = editor.write(&store, "acc").await.unwrap();++ let all_files = flatten(&store, "acc", commit1_oid, &None).await.unwrap();+ assert_eq!(all_files.len(), 3);++ assert_eq!(+ lookup(&store, "acc", commit1_oid, "README.md").await.unwrap().unwrap().0,+ oid_readme+ );+ assert_eq!(+ lookup(&store, "acc", commit1_oid, "resources/docs/a.md").await.unwrap().unwrap().0,+ oid_doc+ );+ assert_eq!(+ lookup(&store, "acc", commit1_oid, "agent/skills/b.py").await.unwrap().unwrap().0,+ oid_skill+ );++ let resources_only = flatten(+ &store,+ "acc",+ commit1_oid,+ &Some(vec!["resources".to_string()]),+ )+ .await+ .unwrap();+ assert_eq!(resources_only.len(), 1);+ assert_eq!(resources_only[0].0, "resources/docs/a.md");++ let mut editor2 = TreeEditor::from_tree(&store, "acc", commit1_oid).await.unwrap();+ let oid_new = oid_hex(b"4444444444444444444444444444444444444444");+ editor2.upsert(&store, "acc", "resources/docs/a.md", oid_new).await.unwrap();+ editor2.remove(&store, "acc", "agent/skills/b.py").await.unwrap();+ editor2.upsert(&store, "acc", "agent/skills/c.py", oid_new).await.unwrap();+ let commit2_oid = editor2.write(&store, "acc").await.unwrap();++ let all_files2 = flatten(&store, "acc", commit2_oid, &None).await.unwrap();+ assert_eq!(all_files2.len(), 3);++ assert_eq!(+ lookup(&store, "acc", commit2_oid, "resources/docs/a.md").await.unwrap().unwrap().0,+ oid_new+ );+ assert!(lookup(&store, "acc", commit2_oid, "agent/skills/b.py").await.unwrap().is_none());+ assert_eq!(+ lookup(&store, "acc", commit2_oid, "agent/skills/c.py").await.unwrap().unwrap().0,+ oid_new+ );++ // Original tree unchanged+ assert_eq!(+ lookup(&store, "acc", commit1_oid, "resources/docs/a.md").await.unwrap().unwrap().0,+ oid_doc+ );+ assert_eq!(+ lookup(&store, "acc", commit1_oid, "agent/skills/b.py").await.unwrap().unwrap().0,+ oid_skill+ );+ }++ // --- Fast Path 2 ---++ /// ObjectStore wrapper recording every `get`/`put` oid, used to prove the+ /// lazy-loading commit path never touches untouched subtrees.+ struct SpyObjectStore {+ inner: crate::git::backends::local::LocalObjectStore,+ gets: std::sync::Mutex<Vec<ObjectId>>,+ puts: std::sync::Mutex<Vec<ObjectId>>,+ }++ impl SpyObjectStore {+ fn new(inner: crate::git::backends::local::LocalObjectStore) -> Self {+ Self {+ inner,+ gets: std::sync::Mutex::new(Vec::new()),+ puts: std::sync::Mutex::new(Vec::new()),+ }+ }+ fn reset(&self) {+ self.gets.lock().unwrap().clear();+ self.puts.lock().unwrap().clear();+ }+ fn was_read(&self, oid: &ObjectId) -> bool {+ self.gets.lock().unwrap().iter().any(|o| o == oid)+ }+ }++ #[async_trait::async_trait]+ impl ObjectStore for SpyObjectStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: bytes::Bytes,+ ) -> Result<(), crate::git::error::ObjectStoreError> {+ self.puts.lock().unwrap().push(*oid);+ self.inner.put(account, oid, zlib_body).await+ }+ async fn get(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> Result<bytes::Bytes, crate::git::error::ObjectStoreError> {+ self.gets.lock().unwrap().push(*oid);+ self.inner.get(account, oid).await+ }+ async fn exists(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> Result<bool, crate::git::error::ObjectStoreError> {+ self.inner.exists(account, oid).await+ }+ }++ #[tokio::test]+ async fn test_fast_path_2_untouched_subtree_not_read() {+ let dir = tempfile::tempdir().unwrap();+ let store = SpyObjectStore::new(+ crate::git::backends::local::LocalObjectStore::new(dir.path()),+ );+ let oid_a = oid_hex(b"1111111111111111111111111111111111111111");+ let oid_b = oid_hex(b"2222222222222222222222222222222222222222");++ // Build a root with two subtrees: resources/ and agent/.+ let mut editor = TreeEditor::empty();+ editor.upsert(&store, "acc", "resources/a.md", oid_a).await.unwrap();+ editor.upsert(&store, "acc", "agent/b.py", oid_b).await.unwrap();+ let root_oid = editor.write(&store, "acc").await.unwrap();++ // Record the untouched subtree's oid (agent/).+ let root = load_tree(&store, "acc", &root_oid).await.unwrap();+ let agent_oid = root.entries.iter().find(|e| e.filename == "agent").unwrap().oid;++ // Reset spy, then edit only inside resources/.+ store.reset();+ let mut editor2 = TreeEditor::from_tree(&store, "acc", root_oid).await.unwrap();+ let oid_c = oid_hex(b"3333333333333333333333333333333333333333");+ editor2.upsert(&store, "acc", "resources/c.md", oid_c).await.unwrap();+ let new_root_oid = editor2.write(&store, "acc").await.unwrap();++ // Fast Path 2: the untouched agent/ subtree was never read...+ assert!(!store.was_read(&agent_oid), "untouched subtree should not be read");++ // ...and the new root reuses its OID as-is (not rewritten).+ let new_root = load_tree(&store, "acc", &new_root_oid).await.unwrap();+ let new_agent_oid = new_root.entries.iter().find(|e| e.filename == "agent").unwrap().oid;+ assert_eq!(new_agent_oid, agent_oid, "untouched subtree OID should be reused");+ }++ #[tokio::test]+ async fn test_upsert_subtree_preserves_siblings() {+ let (_d, store) = make_store();+ let oid_keep = oid_hex(b"1111111111111111111111111111111111111111");+ let oid_old = oid_hex(b"2222222222222222222222222222222222222222");+ let oid_new = oid_hex(b"3333333333333333333333333333333333333333");++ // Base tree: proj/keep.txt and proj/sub/old.txt.+ let mut base = TreeEditor::empty();+ base.upsert(&store, "acc", "proj/keep.txt", oid_keep).await.unwrap();+ base.upsert(&store, "acc", "proj/sub/old.txt", oid_old).await.unwrap();+ let root_oid = base.write(&store, "acc").await.unwrap();++ // Replacement subtree containing new.txt.+ let mut repl = TreeEditor::empty();+ repl.upsert(&store, "acc", "new.txt", oid_new).await.unwrap();+ let repl_oid = repl.write(&store, "acc").await.unwrap();++ // Splice proj/sub with the replacement subtree.+ let mut editor = TreeEditor::from_tree(&store, "acc", root_oid).await.unwrap();+ editor.upsert_subtree(&store, "acc", "proj/sub", repl_oid).await.unwrap();+ let new_root_oid = editor.write(&store, "acc").await.unwrap();++ // Sibling proj/keep.txt is preserved.+ let keep = lookup(&store, "acc", new_root_oid, "proj/keep.txt").await.unwrap();+ assert_eq!(keep.unwrap().0, oid_keep);++ // proj/sub now points at the replacement subtree (containing new.txt).+ let (sub_oid, mode) = lookup(&store, "acc", new_root_oid, "proj/sub").await.unwrap().unwrap();+ assert!(mode.is_tree());+ assert_eq!(sub_oid, repl_oid);+ let new_file = lookup(&store, "acc", new_root_oid, "proj/sub/new.txt").await.unwrap();+ assert_eq!(new_file.unwrap().0, oid_new);+ // Old file is gone.+ assert!(lookup(&store, "acc", new_root_oid, "proj/sub/old.txt").await.unwrap().is_none());+ }+}diff --git a/crates/ragfs/src/git/types.rs b/crates/ragfs/src/git/types.rsnew file mode 100644index 000000000..eccd554ab--- /dev/null+++ b/crates/ragfs/src/git/types.rs@@ -0,0 +1,198 @@+//! DTOs for the Git service API.++use gix_hash::ObjectId;++#[derive(Debug, Clone)]+pub struct CommitRequest {+ pub account: String,+ pub branch: String, // e.g. "main" — NOT the full "refs/heads/main"+ pub message: String,+ /// Explicit candidate paths (account-relative, e.g. "resources/a.md").+ /// `None` means "enumerate the whole account tree".+ pub paths: Option<Vec<String>>,+ pub author_name: String,+ pub author_email: String,+}++#[derive(Debug, Clone)]+pub enum CommitResponse {+ Created { commit_oid: ObjectId, changed: usize },+ /// No path produced an editor change; ref untouched. `commit_oid` is the+ /// existing HEAD (or `ObjectId::null` if the branch did not exist).+ Noop { commit_oid: ObjectId },+}++/// Per-path stat cache entry. Not persisted yet (Fast Path 1 is deferred),+/// but the type lives here so later work can fill in the index.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct IndexEntry {+ pub size: u64,+ pub mtime_ns: i128,+ pub oid: ObjectId,+}++#[derive(Debug, Clone)]+pub struct ShowRequest {+ pub account: String,+ /// One of: 40-hex commit OID, short branch name ("main"),+ /// or full ref path ("refs/heads/main", "refs/tags/v1").+ pub target_ref: String,+ /// If `Some(path)`, return that path's blob bytes from the commit's tree.+ /// If `None`, return the commit's metadata.+ /// `path` is account-relative tree path, e.g. "resources/a.md".+ pub path: Option<String>,+}++#[derive(Debug, Clone)]+pub enum ShowResponse {+ Commit {+ oid: ObjectId,+ tree: ObjectId,+ parents: Vec<ObjectId>,+ author: Actor,+ committer: Actor,+ message: String,+ },+ Blob {+ oid: ObjectId,+ size: u64,+ /// Zero-copy slice over the decompressed object buffer (header + payload).+ /// Cloning is `Arc::clone` — cheap; cloning a `Vec` of the same size is not.+ /// The few bytes of the loose-object header upstream of the payload remain+ /// alive in the backing buffer until the last `Bytes` handle is dropped;+ /// negligible compared to the payload itself.+ bytes: bytes::Bytes,+ },+}++/// Owned, Python-friendly projection of `gix_actor::SignatureRef`.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct Actor {+ pub name: String,+ pub email: String,+ /// Seconds since UNIX epoch.+ pub time_seconds: i64,+ /// Timezone offset in seconds (e.g. +08:00 → 28800).+ pub tz_offset_seconds: i32,+}++/// Input for `GitService::restore`.+#[derive(Debug, Clone)]+pub struct RestoreRequest {+ /// Account this restore applies to.+ pub account: String,+ /// Branch whose HEAD is the parent of the new commit. Defaults to "main"+ /// in callers; this DTO requires the caller to pass it explicitly to+ /// avoid invisible defaults at this layer.+ pub branch: String,+ /// Optional account-relative subtree path to restore, e.g. "resources/proj_a".+ /// `None` restores the whole account tree.+ pub project_dir: Option<String>,+ /// What to restore from. Same resolution rules as `ShowRequest::target_ref`:+ /// 40-hex commit OID / short branch name / full `refs/heads/xxx`.+ pub source_commit: String,+ /// If `true`, compute and return the diff but write nothing — no VFS+ /// writes, no new objects in the object store, no ref update.+ pub dry_run: bool,+ /// Commit message for the new commit. If `None`, a default is generated:+ /// `"restore {project_dir} from {source_oid_short}"`.+ pub message: Option<String>,+ pub author_name: String,+ pub author_email: String,+}++/// Structured diff between two subtrees, computed by `restore`.+///+/// All paths in this struct are **relative to `project_dir`** — they are NOT+/// prefixed. Callers (e.g. a future Python wrapper) prefix them when needed+/// for display.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct RestoreDiff {+ /// Paths whose content in `source_subtree` should be written into the VFS+ /// (creates or overwrites). Carries the blob oid to fetch from the+ /// object store.+ pub to_write: Vec<(String, ObjectId)>,+ /// Paths present in `head_subtree` but absent in `source_subtree`. Must+ /// be removed from the VFS.+ pub to_delete: Vec<String>,+ /// Paths whose oid is identical in both subtrees. Listed only for+ /// reporting; restore does not touch them.+ pub unchanged: Vec<String>,+}++/// Output of `GitService::restore`.+#[derive(Debug, Clone)]+pub enum RestoreResponse {+ /// A new commit was created and the branch ref now points at it.+ Applied {+ /// The new commit's OID — branch HEAD now points here.+ new_commit_oid: ObjectId,+ /// The source commit (after `resolve_ref`) we restored from.+ source_commit: ObjectId,+ /// Previous HEAD oid (parent of `new_commit_oid`).+ parent_commit: ObjectId,+ /// Number of files written through the VFS.+ written: usize,+ /// Number of files deleted through the VFS.+ deleted: usize,+ /// Number of files left untouched because source/head agreed.+ unchanged: usize,+ /// Account-relative paths (prefixed with `project_dir`) that were+ /// written to the VFS. Lets callers trigger downstream side effects+ /// (vector index rebuild, watcher notifications) without re-walking+ /// the tree.+ written_paths: Vec<String>,+ /// Account-relative paths that were removed from the VFS.+ deleted_paths: Vec<String>,+ },+ /// Source subtree byte-equal to head subtree — nothing to do. No new+ /// commit was created; the branch ref is unchanged.+ Noop {+ /// Current HEAD oid (unchanged).+ head: ObjectId,+ /// Source commit oid (after `resolve_ref`).+ source: ObjectId,+ },+ /// `dry_run = true` request — returns the computed diff without+ /// performing any writes.+ DryRun {+ /// The computed diff (paths are relative to `project_dir`).+ diff: RestoreDiff,+ /// Current HEAD oid (would-be parent if applied).+ head: ObjectId,+ /// Source commit oid (after `resolve_ref`).+ source: ObjectId,+ },+}++/// Restore reached the ref-swap step (`new_commit_oid` is now branch HEAD)+/// but at least one per-path write or delete on the VFS failed. The caller+/// must treat this as "HEAD advanced, working tree partial":+/// `written_paths` / `deleted_paths` list paths that *did* reach the VFS+/// and therefore still need reindex; `failed_writes` / `failed_deletes`+/// list the per-path failures that need follow-up.+///+/// Boxed inside `GitError::RestoreWritebackPartial` to keep the enum size+/// bounded — the two path lists can be large on big restores.+#[derive(Debug, Clone)]+pub struct RestoreWritebackPartial {+ pub new_commit_oid: ObjectId,+ pub source_commit: ObjectId,+ pub parent_commit: ObjectId,+ /// Files that *did* reach the VFS (subset of the original plan).+ pub written: usize,+ /// Files that *were* deleted from the VFS (or were idempotently already gone).+ pub deleted: usize,+ /// Files left untouched because source/head agreed.+ pub unchanged: usize,+ /// Account-relative paths whose blob bytes reached the VFS.+ pub written_paths: Vec<String>,+ /// Account-relative paths that were removed from (or already absent from) the VFS.+ pub deleted_paths: Vec<String>,+ /// `(account-relative path, error message)` for writes that failed+ /// after the ref already advanced.+ pub failed_writes: Vec<(String, String)>,+ /// `(account-relative path, error message)` for deletes that failed+ /// with a non-`NotFound` error after the ref already advanced.+ pub failed_deletes: Vec<(String, String)>,+}diff --git a/crates/ragfs/src/git/util.rs b/crates/ragfs/src/git/util.rsnew file mode 100644index 000000000..cee57cd94--- /dev/null+++ b/crates/ragfs/src/git/util.rs@@ -0,0 +1,278 @@+//! Utility functions for Git module++use bytes::Bytes;+use std::io::{Read, Write};++use crate::git::error::RefStoreError;++/// Validate a ref name follows Git naming conventions.+///+/// Checks for:+/// - Empty name+/// - Contains ".."+/// - Starts or ends with "/"+/// - Contains invalid characters+pub fn validate_ref_name(ref_name: &str) -> Result<(), RefStoreError> {+ if ref_name.is_empty() {+ return Err(RefStoreError::InvalidName(+ "ref name cannot be empty".to_string(),+ ));+ }+ if ref_name.contains("..") {+ return Err(RefStoreError::InvalidName(+ "ref name cannot contain '..'".to_string(),+ ));+ }+ if ref_name.starts_with('/') || ref_name.ends_with('/') {+ return Err(RefStoreError::InvalidName(+ "ref name cannot start or end with '/'".to_string(),+ ));+ }+ if ref_name.contains(' ')+ || ref_name.contains('\x00')+ || ref_name.contains('~')+ || ref_name.contains('^')+ || ref_name.contains(':')+ || ref_name.contains('?')+ || ref_name.contains('[')+ || ref_name.contains('*')+ {+ return Err(RefStoreError::InvalidName(+ "ref name contains invalid characters".to_string(),+ ));+ }+ Ok(())+}++/// Compress data using zlib (for Git loose object storage).+pub fn zlib_compress(data: &[u8]) -> Result<Vec<u8>, std::io::Error> {+ let mut encoder = flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::default());+ encoder.write_all(data)?;+ encoder.finish()+}++/// Decompress zlib-compressed data (for reading Git loose objects).+///+/// Pre-allocates a generous output buffer to amortize the `Vec` doubling cost+/// that hurts large blobs (a 100 MiB payload otherwise triggers ~27 reallocs).+/// The hint assumes a worst-case compression ratio of ~4×; capped at 64 MiB+/// so a pathologically small-but-compressible header doesn't reserve absurd+/// amounts of memory. Exceeding the hint still works — `Vec` will grow.+pub fn zlib_decompress(data: &[u8]) -> Result<Vec<u8>, std::io::Error> {+ const HINT_CAP: usize = 64 * 1024 * 1024;+ let hint = data.len().saturating_mul(4).min(HINT_CAP);+ let mut decoded = Vec::with_capacity(hint);+ let mut decoder = flate2::read::ZlibDecoder::new(data);+ decoder.read_to_end(&mut decoded)?;+ Ok(decoded)+}++/// Parse a Git loose object header, returning (kind, size, header_end_offset).+pub fn parse_object_header(data: &[u8]) -> Result<(gix_object::Kind, u64, usize), crate::git::error::ObjectStoreError> {+ gix_object::decode::loose_header(data).map_err(|e| {+ crate::git::error::ObjectStoreError::Backend(format!("invalid object header: {e}"))+ })+}++/// Read and decompress a Git object from ObjectStore, returning the full+/// uncompressed bytes (including header).+pub async fn read_object(+ store: &dyn crate::git::object_store::ObjectStore,+ account: &str,+ oid: &gix_hash::ObjectId,+) -> Result<Bytes, crate::git::error::ObjectStoreError> {+ let compressed = store.get(account, oid).await?;+ let decompressed = zlib_decompress(&compressed)+ .map_err(|e| crate::git::error::ObjectStoreError::Zlib(e.to_string()))?;+ Ok(Bytes::from(decompressed))+}++/// Serialize, compress, and write a Git object to ObjectStore.+/// Returns the object's ObjectId.+pub async fn write_object(+ store: &dyn crate::git::object_store::ObjectStore,+ account: &str,+ kind: gix_object::Kind,+ data: &[u8],+) -> Result<gix_hash::ObjectId, crate::git::error::ObjectStoreError> {+ let header = gix_object::encode::loose_header(kind, data.len() as u64);+ let oid = gix_object::compute_hash(gix_hash::Kind::Sha1, kind, data);+ let mut full = Vec::with_capacity(header.len() + data.len());+ full.extend_from_slice(&header);+ full.extend_from_slice(data);+ let compressed = zlib_compress(&full)?;+ store.put(account, &oid, Bytes::from(compressed)).await?;+ Ok(oid)+}++/// Same as [`write_object`], but runs an `exists` precheck before compressing+/// and putting (Fast Path 3). If the object is already present, the zlib+/// compression and `put` are skipped and the oid is returned directly. `put`+/// is itself idempotent, so this precheck is purely a performance optimization+/// (saves S3 body upload / local zlib compression for duplicate blobs).+pub async fn write_object_if_absent(+ store: &dyn crate::git::object_store::ObjectStore,+ account: &str,+ kind: gix_object::Kind,+ data: &[u8],+) -> Result<gix_hash::ObjectId, crate::git::error::ObjectStoreError> {+ let oid = gix_object::compute_hash(gix_hash::Kind::Sha1, kind, data);+ if store.exists(account, &oid).await? {+ return Ok(oid);+ }+ let header = gix_object::encode::loose_header(kind, data.len() as u64);+ let mut full = Vec::with_capacity(header.len() + data.len());+ full.extend_from_slice(&header);+ full.extend_from_slice(data);+ let compressed = zlib_compress(&full)?;+ store.put(account, &oid, Bytes::from(compressed)).await?;+ Ok(oid)+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn test_validate_ref_name() {+ assert!(validate_ref_name("refs/heads/main").is_ok());+ assert!(validate_ref_name("refs/tags/v1.0").is_ok());+ assert!(validate_ref_name("HEAD").is_ok());++ assert!(validate_ref_name("").is_err());+ assert!(validate_ref_name("..").is_err());+ assert!(validate_ref_name("refs/../heads").is_err());+ assert!(validate_ref_name("/refs/heads").is_err());+ assert!(validate_ref_name("refs/heads/ ").is_err());+ assert!(validate_ref_name("refs~head").is_err());+ assert!(validate_ref_name("refs^head").is_err());+ assert!(validate_ref_name("refs:head").is_err());+ assert!(validate_ref_name("refs?head").is_err());+ assert!(validate_ref_name("refs[head]").is_err());+ assert!(validate_ref_name("refs*head").is_err());+ }++ #[test]+ fn test_zlib_round_trip() {+ let original = b"tree 15\0hello world!!!";+ let compressed = zlib_compress(original).unwrap();+ let decompressed = zlib_decompress(&compressed).unwrap();+ assert_eq!(decompressed, original);+ }++ #[test]+ fn test_parse_object_header_tree() {+ let data = b"tree 15\0entries data";+ let (kind, size, offset) = parse_object_header(data).unwrap();+ assert_eq!(kind, gix_object::Kind::Tree);+ assert_eq!(size, 15);+ assert_eq!(offset, 8);+ }++ #[test]+ fn test_parse_object_header_blob() {+ let data = b"blob 5\0hello";+ let (kind, size, offset) = parse_object_header(data).unwrap();+ assert_eq!(kind, gix_object::Kind::Blob);+ assert_eq!(size, 5);+ assert_eq!(offset, 7);+ }++ #[tokio::test]+ async fn test_write_read_object_round_trip() {+ use tempfile::tempdir;+ use crate::git::backends::local::LocalObjectStore;++ let temp_dir = tempdir().unwrap();+ let store = LocalObjectStore::new(temp_dir.path());++ let data = b"hello tree bytes";+ let kind = gix_object::Kind::Blob;++ // Write the object+ let oid = write_object(&store, "test-account", kind, data).await.unwrap();++ // Read the object back+ let raw = read_object(&store, "test-account", &oid).await.unwrap();++ // Parse and validate header+ let (parsed_kind, size, offset) = parse_object_header(&raw).unwrap();+ assert_eq!(parsed_kind, kind);+ assert_eq!(size, data.len() as u64);++ // Validate body+ assert_eq!(&raw[offset..], data);++ // Validate OID matches expected+ let expected_oid = gix_object::compute_hash(gix_hash::Kind::Sha1, kind, data);+ assert_eq!(oid, expected_oid);+ }++ #[tokio::test]+ async fn test_write_object_if_absent_skips_put_on_second_call() {+ use std::sync::atomic::{AtomicUsize, Ordering};+ use std::sync::Arc;+ use tempfile::tempdir;+ use crate::git::backends::local::LocalObjectStore;+ use crate::git::object_store::ObjectStore;+ use crate::git::error::ObjectStoreError;+ use gix_hash::ObjectId;++ struct CountingStore {+ inner: LocalObjectStore,+ puts: AtomicUsize,+ exists_calls: AtomicUsize,+ }++ #[async_trait::async_trait]+ impl ObjectStore for CountingStore {+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: Bytes,+ ) -> Result<(), ObjectStoreError> {+ self.puts.fetch_add(1, Ordering::SeqCst);+ self.inner.put(account, oid, zlib_body).await+ }+ async fn get(&self, account: &str, oid: &ObjectId) -> Result<Bytes, ObjectStoreError> {+ self.inner.get(account, oid).await+ }+ async fn exists(&self, account: &str, oid: &ObjectId) -> Result<bool, ObjectStoreError> {+ self.exists_calls.fetch_add(1, Ordering::SeqCst);+ self.inner.exists(account, oid).await+ }+ }++ let temp_dir = tempdir().unwrap();+ let store = Arc::new(CountingStore {+ inner: LocalObjectStore::new(temp_dir.path()),+ puts: AtomicUsize::new(0),+ exists_calls: AtomicUsize::new(0),+ });++ let data = b"duplicate blob content";+ let kind = gix_object::Kind::Blob;++ let oid1 = write_object_if_absent(store.as_ref(), "acct", kind, data)+ .await+ .unwrap();+ assert_eq!(store.puts.load(Ordering::SeqCst), 1);++ // Second call with identical data: should hit exists and skip put.+ let oid2 = write_object_if_absent(store.as_ref(), "acct", kind, data)+ .await+ .unwrap();+ assert_eq!(oid1, oid2);+ assert_eq!(store.puts.load(Ordering::SeqCst), 1, "put must not be called again");+ assert_eq!(store.exists_calls.load(Ordering::SeqCst), 2);++ // Object is readable and oid matches compute_hash.+ let raw = read_object(store.as_ref(), "acct", &oid1).await.unwrap();+ let (parsed_kind, _size, offset) = parse_object_header(&raw).unwrap();+ assert_eq!(parsed_kind, kind);+ assert_eq!(&raw[offset..], data);+ let expected = gix_object::compute_hash(gix_hash::Kind::Sha1, kind, data);+ assert_eq!(oid1, expected);+ }+}diff --git a/crates/ragfs/src/lib.rs b/crates/ragfs/src/lib.rsindex 47106ddc6..f4582e298 100644--- a/crates/ragfs/src/lib.rs+++ b/crates/ragfs/src/lib.rs@@ -34,6 +34,7 @@ pub mod cache;pub mod core;pub mod crypto;pub mod multibackend;+pub mod git;pub mod plugins;pub mod shape;diff --git a/crates/ragfs/tests/git_s3_integration.rs b/crates/ragfs/tests/git_s3_integration.rsnew file mode 100644index 000000000..e3816a0bd--- /dev/null+++ b/crates/ragfs/tests/git_s3_integration.rs@@ -0,0 +1,587 @@+//! Integration tests for the S3/TOS git storage backend (audit plan §A2).+//!+//! These tests exercise [`S3ObjectStore`] / [`S3RefStore`] against a *real*+//! S3-compatible backend (TOS / MinIO / LocalStack). They are gated behind the+//! `s3` feature **and** the presence of a usable `[git]` + `[git.s3]` section in+//! the OpenViking config file (`ov.conf`), mirroring the skip strategy used by+//! the Python `test_fs_binding_s3.py` suite.+//!+//! Config resolution (first hit wins):+//! 1. `OV_GIT_S3_CONF` env var (explicit path to an `ov.conf` JSON file)+//! 2. `OPENVIKING_CONFIG_FILE` env var+//! 3. `~/.openviking/ov.conf`+//! 4. `/etc/openviking/ov.conf`+//!+//! The relevant section (JSON) looks like:+//! ```json+//! {+//! "git": {+//! "enabled": true,+//! "backend": "s3",+//! "s3": {+//! "bucket": "<your-tos-bucket>",+//! "region": "cn-beijing",+//! "endpoint": "https://tos-s3-cn-beijing.volces.com",+//! "access_key": "<ak>",+//! "secret_key": "<sk>",+//! "prefix": ".ovgit",+//! "use_path_style": false,+//! "cas_mode": "native"+//! }+//! }+//! }+//! ```+//!+//! When no usable config is found, each test prints a notice and returns+//! successfully (treated as skipped) so default `cargo test` runs stay green.+//!+//! Run against TOS:+//! ```bash+//! OV_GIT_S3_CONF=/path/to/ov.conf \+//! cargo test -p ragfs --features s3 --test git_s3_integration -- --nocapture+//! ```+//! Tests namespace every key under `{prefix}/_it/{uuid}` and use a random+//! account per test, so concurrent runs never collide and never touch real data.++#![cfg(feature = "s3")]++use std::path::PathBuf;+use std::sync::Arc;++use bytes::Bytes;+use gix_hash::ObjectId;++use ragfs::core::filesystem::FileSystem;+use ragfs::git::backends::local::LocalObjectStore;+use ragfs::git::backends::s3::{CasMode, S3Config, S3ObjectStore, S3RefStore};+use ragfs::git::error::RefStoreError;+use ragfs::git::object_store::ObjectStore;+use ragfs::git::ref_store::RefStore;+use ragfs::git::service::GitService;+use ragfs::git::types::{+ CommitRequest, CommitResponse, RestoreRequest, RestoreResponse, ShowRequest, ShowResponse,+};+use ragfs::git::util::zlib_compress;+use ragfs::plugins::localfs::LocalFileSystem;++/// Resolve the `ov.conf` path using the same chain documented above.+fn resolve_conf_path() -> Option<PathBuf> {+ let candidates = [+ std::env::var("OV_GIT_S3_CONF").ok(),+ std::env::var("OPENVIKING_CONFIG_FILE").ok(),+ std::env::var("HOME")+ .ok()+ .map(|h| format!("{h}/.openviking/ov.conf")),+ Some("/etc/openviking/ov.conf".to_string()),+ ];+ candidates+ .into_iter()+ .flatten()+ .map(PathBuf::from)+ .find(|p| p.exists())+}++/// Load and build an [`S3Config`] from the resolved `ov.conf`, namespacing the+/// `prefix` under a unique `_it/{uuid}` segment for test isolation.+///+/// Returns `None` (treated as "skip") when no config file exists, when git is+/// not enabled, when the backend is not `s3`, or when the `[git.s3]` section is+/// missing required fields (`bucket`/`region`).+fn load_s3_config() -> Option<S3Config> {+ let path = resolve_conf_path()?;+ let raw = std::fs::read_to_string(&path).ok()?;+ let root: serde_json::Value = serde_json::from_str(&raw).ok()?;++ // `git` may live at the top level (OpenVikingConfig.git) or, defensively,+ // under `storage.git`.+ let git = root+ .get("git")+ .or_else(|| root.get("storage").and_then(|s| s.get("git")))?;++ if !git.get("enabled").and_then(|v| v.as_bool()).unwrap_or(false) {+ return None;+ }+ if git.get("backend").and_then(|v| v.as_str()) != Some("s3") {+ return None;+ }++ let s3 = git.get("s3")?;+ let bucket = s3.get("bucket").and_then(|v| v.as_str())?.to_string();+ let region = s3.get("region").and_then(|v| v.as_str())?.to_string();+ if bucket.is_empty() || region.is_empty() {+ return None;+ }++ let str_opt = |key: &str| {+ s3.get(key)+ .and_then(|v| v.as_str())+ .filter(|s| !s.is_empty())+ .map(|s| s.to_string())+ };++ let base_prefix = str_opt("prefix").unwrap_or_else(|| ".ovgit".to_string());+ let prefix = format!(+ "{}/_it/{}",+ base_prefix.trim_end_matches('/'),+ uuid::Uuid::new_v4().simple()+ );++ let endpoint = str_opt("endpoint");+ let access_key_id = str_opt("access_key");+ let secret_access_key = str_opt("secret_key");+ let use_path_style = s3+ .get("use_path_style")+ .and_then(|v| v.as_bool())+ .unwrap_or(true);+ let cas_mode = match s3.get("cas_mode").and_then(|v| v.as_str()) {+ Some("redis_lock") => CasMode::RedisLock,+ _ => CasMode::Native,+ };++ Some(S3Config {+ bucket,+ prefix,+ region,+ endpoint,+ access_key_id,+ secret_access_key,+ use_path_style,+ cas_mode,+ })+}++/// Build a random account id so concurrent tests never share namespaces.+fn random_account() -> String {+ format!("acct-{}", uuid::Uuid::new_v4().simple())+}++/// Build a valid zlib-compressed loose object body together with its object id.+fn loose_object(data: &[u8]) -> (ObjectId, Bytes) {+ let kind = gix_object::Kind::Blob;+ let header = gix_object::encode::loose_header(kind, data.len() as u64);+ let oid = gix_object::compute_hash(gix_hash::Kind::Sha1, kind, data);+ let mut full = Vec::with_capacity(header.len() + data.len());+ full.extend_from_slice(&header);+ full.extend_from_slice(data);+ let compressed = zlib_compress(&full).expect("zlib compress");+ (oid, Bytes::from(compressed))+}++/// Compute a deterministic [`ObjectId`] from arbitrary bytes (used as ref values).+fn oid_of(data: &[u8]) -> ObjectId {+ gix_object::compute_hash(gix_hash::Kind::Sha1, gix_object::Kind::Blob, data)+}++/// Print a skip notice once and return `true` when no S3 config is available.+macro_rules! cfg_or_skip {+ ($test:expr) => {{+ match load_s3_config() {+ Some(cfg) => cfg,+ None => {+ eprintln!(+ "[skip] {}: no usable [git.s3] config (set OV_GIT_S3_CONF to an ov.conf \+ with git.enabled=true, backend=\"s3\")",+ $test+ );+ return;+ }+ }+ }};+}++/// §A2.1 — ObjectStore round-trip + idempotency + not-found behavior.+#[tokio::test]+async fn s3_object_store_round_trip() {+ let cfg = cfg_or_skip!("s3_object_store_round_trip");+ let account = random_account();+ let store = S3ObjectStore::from_config(cfg)+ .await+ .expect("build S3ObjectStore");++ let (oid, body) = loose_object(b"hello viking s3 round-trip");++ // First write succeeds.+ store.put(&account, &oid, body.clone()).await.expect("put #1");+ // Second write of identical content is idempotent (must not error).+ store.put(&account, &oid, body.clone()).await.expect("put #2 idempotent");++ // get returns the exact zlib bytes we stored.+ let fetched = store.get(&account, &oid).await.expect("get");+ assert_eq!(fetched, body, "stored and fetched bytes must match exactly");++ // exists is true for a written object.+ assert!(store.exists(&account, &oid).await.expect("exists"));++ // A never-written oid: get -> NotFound, exists -> false.+ let (missing_oid, _) = loose_object(b"this object was never written to s3");+ match store.get(&account, &missing_oid).await {+ Err(ragfs::git::error::ObjectStoreError::NotFound(o)) => assert_eq!(o, missing_oid),+ other => panic!("expected NotFound, got {other:?}"),+ }+ assert!(!store.exists(&account, &missing_oid).await.expect("exists missing"));+}++/// §A2.2 — RefStore CAS create: first create wins, second create conflicts.+#[tokio::test]+async fn s3_ref_store_cas_create() {+ let cfg = cfg_or_skip!("s3_ref_store_cas_create");+ let account = random_account();+ let store = S3RefStore::from_config(cfg)+ .await+ .expect("build S3RefStore");++ let ref_name = "refs/heads/main";+ let a = oid_of(b"commit-A");+ let b = oid_of(b"commit-B");++ // create-if-absent succeeds.+ store+ .cas_update(&account, ref_name, None, a)+ .await+ .expect("first create");+ assert_eq!(store.read(&account, ref_name).await.expect("read"), a);++ // A second create-if-absent must conflict (ref already exists).+ match store.cas_update(&account, ref_name, None, b).await {+ Err(RefStoreError::Conflict { expected, actual }) => {+ assert_eq!(expected, None);+ assert_eq!(actual, Some(a));+ }+ other => panic!("expected Conflict, got {other:?}"),+ }+ // Value must be unchanged.+ assert_eq!(store.read(&account, ref_name).await.expect("read after conflict"), a);+}++/// §A2.3 — RefStore CAS advance: expected==current moves the ref forward.+#[tokio::test]+async fn s3_ref_store_cas_advance() {+ let cfg = cfg_or_skip!("s3_ref_store_cas_advance");+ let account = random_account();+ let store = S3RefStore::from_config(cfg)+ .await+ .expect("build S3RefStore");++ let ref_name = "refs/heads/main";+ let a = oid_of(b"commit-A");+ let b = oid_of(b"commit-B");++ store.cas_update(&account, ref_name, None, a).await.expect("create A");+ store+ .cas_update(&account, ref_name, Some(a), b)+ .await+ .expect("advance A -> B");+ assert_eq!(store.read(&account, ref_name).await.expect("read"), b);+}++/// §A2.4 — RefStore CAS conflict: a stale `expected` is rejected with the+/// actual current value reported.+#[tokio::test]+async fn s3_ref_store_cas_conflict() {+ let cfg = cfg_or_skip!("s3_ref_store_cas_conflict");+ let account = random_account();+ let store = S3RefStore::from_config(cfg)+ .await+ .expect("build S3RefStore");++ let ref_name = "refs/heads/main";+ let a = oid_of(b"commit-A");+ let stale = oid_of(b"commit-STALE");+ let c = oid_of(b"commit-C");++ store.cas_update(&account, ref_name, None, a).await.expect("create A");++ match store.cas_update(&account, ref_name, Some(stale), c).await {+ Err(RefStoreError::Conflict { expected, actual }) => {+ assert_eq!(expected, Some(stale));+ assert_eq!(actual, Some(a));+ }+ other => panic!("expected Conflict, got {other:?}"),+ }+ assert_eq!(store.read(&account, ref_name).await.expect("read"), a);+}++/// §A2.5 — RefStore list: all refs under a prefix are returned (exercises the+/// `list_objects_v2` pagination path).+#[tokio::test]+async fn s3_ref_store_list() {+ let cfg = cfg_or_skip!("s3_ref_store_list");+ let account = random_account();+ let store = S3RefStore::from_config(cfg)+ .await+ .expect("build S3RefStore");++ let entries = [+ ("refs/heads/main", oid_of(b"main")),+ ("refs/heads/dev", oid_of(b"dev")),+ ("refs/heads/release", oid_of(b"release")),+ ];+ for (name, oid) in &entries {+ store.cas_update(&account, name, None, *oid).await.expect("create ref");+ }++ let mut listed = store.list(&account, "refs/heads").await.expect("list");+ listed.sort();++ let mut expected: Vec<(String, ObjectId)> =+ entries.iter().map(|(n, o)| (n.to_string(), *o)).collect();+ expected.sort();++ assert_eq!(listed, expected);+}++/// §A2.6 — Backend equivalence: the same object is byte-identical and equally+/// visible whether stored via the local or the S3 backend.+#[tokio::test]+async fn backend_equivalence_local_vs_s3() {+ let cfg = cfg_or_skip!("backend_equivalence_local_vs_s3");+ let account = random_account();++ let s3 = S3ObjectStore::from_config(cfg)+ .await+ .expect("build S3ObjectStore");+ let tmp = tempfile::tempdir().expect("tempdir");+ let local = LocalObjectStore::new(tmp.path());++ let (oid, body) = loose_object(b"backend equivalence payload \x00\x01\x02 binary-ish");++ let s3: Arc<dyn ObjectStore> = Arc::new(s3);+ let local: Arc<dyn ObjectStore> = Arc::new(local);++ for store in [&s3, &local] {+ store.put(&account, &oid, body.clone()).await.expect("put");+ assert!(store.exists(&account, &oid).await.expect("exists"));+ }++ let from_s3 = s3.get(&account, &oid).await.expect("s3 get");+ let from_local = local.get(&account, &oid).await.expect("local get");++ assert_eq!(from_s3, body, "s3 bytes must match input");+ assert_eq!(from_local, body, "local bytes must match input");+ assert_eq!(from_s3, from_local, "s3 and local stored bytes must be identical");+}++// ─────────────────────────────────────────────────────────────────────────+// §A3 — End-to-end GitService over the S3/TOS backend.+//+// These mirror the local-backend service tests in `src/git/service.rs`, but+// wire `GitService` to `S3ObjectStore` + `S3RefStore` (loaded from `ov.conf`)+// and a real `LocalFileSystem` working tree rooted at a temp dir. The working+// tree layout matches production: each account lives under `/local/{account}`+// relative to the mount base.+// ─────────────────────────────────────────────────────────────────────────++/// Build a `GitService` backed by S3 stores plus a fresh `LocalFileSystem`+/// working tree. Returns the service, the kept-alive temp dir, and the+/// absolute account root path (`{tmp}/local/{account}`) for direct file IO.+fn make_s3_service(+ cfg: S3Config,+ account: &str,+) -> impl std::future::Future<Output = (GitService, tempfile::TempDir, PathBuf)> + '_ {+ async move {+ let object_store: Arc<dyn ObjectStore> = Arc::new(+ S3ObjectStore::from_config(cfg.clone())+ .await+ .expect("build S3ObjectStore"),+ );+ let ref_store: Arc<dyn RefStore> = Arc::new(+ S3RefStore::from_config(cfg)+ .await+ .expect("build S3RefStore"),+ );++ let work_dir = tempfile::tempdir().expect("tempdir");+ let acct_root = work_dir.path().join("local").join(account);+ std::fs::create_dir_all(&acct_root).expect("create account root");+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).expect("localfs"));++ let svc = GitService::new(vfs, object_store, ref_store);+ (svc, work_dir, acct_root)+ }+}++/// Build a `CommitRequest` with fixed test author info.+fn commit_req(account: &str, branch: &str, message: &str, paths: Option<Vec<String>>) -> CommitRequest {+ CommitRequest {+ account: account.to_string(),+ branch: branch.to_string(),+ message: message.to_string(),+ paths,+ author_name: "tester".to_string(),+ author_email: "[email protected]".to_string(),+ }+}++/// §A3.1 — commit → show(path) returns the exact blob bytes that were written.+#[tokio::test]+async fn s3_e2e_commit_then_show_blob_round_trip() {+ let cfg = cfg_or_skip!("s3_e2e_commit_then_show_blob_round_trip");+ let account = random_account();+ let (svc, _work_dir, acct_root) = make_s3_service(cfg, &account).await;++ // Binary-ish payload to guard against any string-vs-bytes regression.+ let body: &[u8] = b"hello viking s3 e2e \x00\x01\x02\nline2\n";+ std::fs::create_dir_all(acct_root.join("resources")).expect("mkdir resources");+ std::fs::write(acct_root.join("resources/a.md"), body).expect("write a.md");++ match svc+ .commit(commit_req(&account, "main", "first", None))+ .await+ .expect("commit")+ {+ CommitResponse::Created { .. } => {}+ other => panic!("expected Created, got {other:?}"),+ }++ let resp = svc+ .show(ShowRequest {+ account: account.clone(),+ target_ref: "main".into(),+ path: Some("resources/a.md".into()),+ })+ .await+ .expect("show");++ match resp {+ ShowResponse::Blob { bytes, size, .. } => {+ assert_eq!(bytes.as_ref(), body, "blob bytes must match written content");+ assert_eq!(size, body.len() as u64);+ }+ other => panic!("expected Blob, got {other:?}"),+ }+}++/// §A3.2 — restore to an older commit rolls back the working tree and creates+/// a *new* commit whose parent is the current HEAD (forward-only history).+#[tokio::test]+async fn s3_e2e_restore_rolls_back_and_advances_head() {+ let cfg = cfg_or_skip!("s3_e2e_restore_rolls_back_and_advances_head");+ let account = random_account();+ let (svc, _work_dir, acct_root) = make_s3_service(cfg, &account).await;++ let proj = acct_root.join("resources/proj_a");+ std::fs::create_dir_all(&proj).expect("mkdir proj_a");++ // Source commit: a.md=v1, b.md=v1.+ std::fs::write(proj.join("a.md"), b"A v1").unwrap();+ std::fs::write(proj.join("b.md"), b"B v1").unwrap();+ let source_oid = match svc+ .commit(commit_req(&account, "main", "source", None))+ .await+ .expect("commit source")+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // HEAD commit: rewrite a.md, delete b.md, add c.md.+ std::fs::write(proj.join("a.md"), b"A v2").unwrap();+ std::fs::remove_file(proj.join("b.md")).unwrap();+ std::fs::write(proj.join("c.md"), b"C new").unwrap();+ let head_oid = match svc+ .commit(commit_req(+ &account,+ "main",+ "head",+ Some(vec![+ "resources/proj_a/a.md".to_string(),+ "resources/proj_a/b.md".to_string(),+ "resources/proj_a/c.md".to_string(),+ ]),+ ))+ .await+ .expect("commit head")+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Restore the project subtree back to the source commit.+ let resp = svc+ .restore(RestoreRequest {+ account: account.clone(),+ branch: "main".into(),+ project_dir: Some("resources/proj_a".into()),+ source_commit: source_oid.to_hex().to_string(),+ dry_run: false,+ message: Some("rewind proj_a".into()),+ author_name: "tester".into(),+ author_email: "[email protected]".into(),+ })+ .await+ .expect("restore");++ match resp {+ RestoreResponse::Applied {+ source_commit,+ parent_commit,+ written,+ deleted,+ ..+ } => {+ assert_eq!(source_commit, source_oid);+ assert_eq!(parent_commit, head_oid, "new commit's parent MUST be HEAD, not source");+ assert_eq!(written, 2, "a.md rewrite + b.md recreate");+ assert_eq!(deleted, 1, "c.md removed");+ }+ other => panic!("expected Applied, got {other:?}"),+ }++ // Working tree rolled back to the source snapshot.+ assert_eq!(std::fs::read(proj.join("a.md")).unwrap(), b"A v1", "a.md rolled back");+ assert_eq!(std::fs::read(proj.join("b.md")).unwrap(), b"B v1", "b.md restored");+ assert!(!proj.join("c.md").exists(), "c.md must be deleted");++ // HEAD advanced to a brand-new commit (forward-only), parented on the old HEAD.+ let new_head = svc+ .show(ShowRequest {+ account: account.clone(),+ target_ref: "main".into(),+ path: None,+ })+ .await+ .expect("show head");+ match new_head {+ ShowResponse::Commit { oid, parents, .. } => {+ assert_ne!(oid, head_oid, "restore must create a new commit");+ assert_ne!(oid, source_oid, "HEAD is a new commit, not the source");+ assert_eq!(parents, vec![head_oid], "new commit parent must be prior HEAD");+ }+ other => panic!("expected Commit, got {other:?}"),+ }+}++/// §A3.3 — idempotency: committing again with no working-tree change is a Noop+/// and leaves the branch ref pointing at the same commit.+#[tokio::test]+async fn s3_e2e_commit_noop_when_unchanged() {+ let cfg = cfg_or_skip!("s3_e2e_commit_noop_when_unchanged");+ let account = random_account();+ let (svc, _work_dir, acct_root) = make_s3_service(cfg, &account).await;++ std::fs::create_dir_all(acct_root.join("resources")).unwrap();+ std::fs::write(acct_root.join("resources/a.md"), b"stable content").unwrap();++ let first_oid = match svc+ .commit(commit_req(&account, "main", "first", None))+ .await+ .expect("commit first")+ {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created, got {other:?}"),+ };++ // Second commit with identical tree state — must be a Noop pointing at the+ // existing HEAD.+ match svc+ .commit(commit_req(&account, "main", "second", None))+ .await+ .expect("commit second")+ {+ CommitResponse::Noop { commit_oid } => {+ assert_eq!(commit_oid, first_oid, "Noop must report the unchanged HEAD oid");+ }+ other => panic!("expected Noop, got {other:?}"),+ }+}diff --git a/docs/design/git-version-control-design.md b/docs/design/git-version-control-design.mdnew file mode 100644index 000000000..041a066ed--- /dev/null+++ b/docs/design/git-version-control-design.md@@ -0,0 +1,1257 @@+# OpenViking 多版本管理技术方案 — 基于 Gitoxide 的 in-process Git 集成++> 💡 **一句话摘要**:在现有 OpenViking 的 RAGFS Rust 实现中嵌入一套基于 `gitoxide` 的 in-process Git 服务,以 **账号(account\_id)粒度** 提供 `commit / restore / show` 三个版本管理原语;通过 PyO3 binding 直接被 `VikingFS` Python 层调用,全程零 HTTP、零额外进程,Git 对象/Ref 后端复用现有 `localfs`/`s3fs` 客户端,实现"本地或远程"对称配置。++# 1. 背景与目标++## 1.1 业务背景++OpenViking 现有存储架构是一套以 `viking://` URI 为入口的双层抽象:上层 `VikingFS`(Python)负责 URI 规范化、L0/L1 摘要、向量同步、租户隔离;下层 RAGFS(Rust + PyO3 binding)提供 `FileSystem` trait 与 `MountableFS` radix-trie 路由,实际数据落到 `localfs`、`s3fs`、`memfs` 等插件后端。++在持续运行过程中,用户/Agent 对 `viking://resources/`、`viking://agent/skills/` 等命名空间的写入是连续且不可逆的——出错后无法回滚,跨多个文件的"逻辑事务"难以原子化捕获,实验性改动需要手动备份。这些场景的本质需求都是一套**面向账号的多版本快照机制**,语义与 Git 的 commit/restore/show 高度同构。++## 1.2 设计目标++- **显式版本化**:用户/Agent 通过 API 显式触发 commit/restore/show,不引入隐式 hook,避免影响现有写链路的延迟与一致性语义+- **账号粒度仓库**:每个 `account_id` 一个逻辑 Git 仓库,跨 scope (resources/agent/user/session) 共享同一棵 root tree,支持跨 scope 的原子快照+- **多后端对称**:Git objects / refs 的实际存储类型与 resources 目录一致,可在配置中切换本地(local)或远程(s3),运维心智零增量+- **零进程膨胀**:Git 服务以 in-process binding 形式嵌入现有 RAGFS,共享 Tokio runtime 与配置加载链路,不引入新 HTTP server+- **对现有代码侵入最小**:不修改 `content_write.py`、`viking_fs.write/rm/mv` 等核心写链路,仅在 `VikingFS` 上增加 3 个新方法+- **定向恢复 (restore)**:支持以 **(project\_dir, commit\_id)** 为输入,将指定 project 目录恢复到目标 commit 的快照状态,并以 HEAD 为父节点*正向生成一个新 commit*。非目标 project 目录保持当前最新状态不动。++## 1.3 非目标 (Out of Scope)++- 不实现自动 commit hook (首版纯主动 API 触发)+- 不实现分支 merge / rebase / cherry-pick / push/pull (首版只覆盖快照 + 回滚 + 查看)+- 不暴露 Git 数据到 `viking://` 用户命名空间 (避免被用户误删/误改)+- 不支持向量索引数据的版本化 (向量索引由 watcher 异步重建, restore 后需触发重建;L0/L1 派生文件已纳入版本管理)+- 不支持 ref 回退式 checkout:本方案不提供 "把 main / HEAD 指针直接移动到旧 commit" 的能力。所有恢复操作都通过正向新增 commit 实现,保证 HEAD 单调前进、commit 链完整可审计。如需查看旧版本,使用 **show** 接口的只读路径。++***++# 2. 核心设计决策++| 决策 | 设计含义 | 替代方案被淘汰的原因 |+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |+| **单 Repo per account\_id** | 同一账号下的 `resources/`、`agent/`、`user/`、`session/` 全部在一棵 root tree 之下;一次 commit 可覆盖任意 scope 的子集 | per-resource repo 会产生 N×账号数量的索引数据,跨 resource 的"事务性快照"需要协调多 repo,复杂度高 |+| **纯 API 触发,不接 hook** | `content_write.py` / `viking_fs.write/rm/mv` 完全不动;Git 仅通过 `VikingFS.commit/restore/show` 三个新方法被显式调用 | hook 模式会让每次小写入都触发 Git 写入,放大延迟、放大冲突窗口、放大 ref CAS 失败率;首版优先简单 |+| **Git 存储后端与 resources 同构** | 定义 `ObjectStore` / `RefStore` trait,提供 local 与 s3 两种实现,直接复用 `plugins::localfs::LocalFileSystem` 和 `plugins::s3fs::S3Client` | 独立实现 Git 存储后端会重复造轮子;走 `MountableFS` 又会让 Git 数据进入用户命名空间 |+| **嵌入为 crates/ragfs 子模块** | 新增 `crates/ragfs/src/git/` 模块,与 `core/`、`plugins/`、`server/` 平级;PyO3 binding 在 `RAGFSBindingClient` 上加 3 个方法 | 独立 crate 会引入额外配置、额外 runtime、额外鉴权;`ServicePlugin` 又无法表达 commit 这种非文件操作的语义 |+| **暴露方式 = PyO3 binding,非 HTTP** | 三个新方法挂在现有 `RAGFSBindingClient` 上,通过 `AsyncAGFSClient.run` 由 `VikingFS` 调用,与 `ls/read/write` 一致 | HTTP server 路径在 OpenViking 当前架构中已是 legacy,生产路径是 in-process binding |++***++# 3. 整体架构++## 3.1 分层与依赖关系++```mermaid+flowchart TB+ subgraph Py[Python 层]+ VFS["VikingFS+commit / checkout / show"]+ Async["AsyncAGFSClient+(asyncio.to_thread)"]+ end++ subgraph BindCrate["crates/ragfs-python (PyO3 cdylib)"]+ RBC["RAGFSBindingClient++ git_commit / git_checkout / git_show"]+ end++ subgraph CoreCrate[crates/ragfs]+ MFS["core/MountableFS+(现有 VFS 路由)"]+ Plugins["plugins/+localfs · s3fs · memfs ..."]+ GitMod["git/ (新增)+GitService · ObjectStore · RefStore"]+ end++ subgraph Backends[底层存储后端]+ Local["LocalFileSystem+(本地磁盘)"]+ S3["S3Client+(TOS / S3 / OSS)"]+ end++ VFS --> Async+ Async --> RBC+ RBC --> MFS+ RBC --> GitMod+ GitMod -- "checkout 写回阶段" --> MFS+ MFS --> Plugins+ Plugins --> Local+ Plugins --> S3+ GitMod -- "直接持有 struct+(不经过 MountableFS)" --> Local+ GitMod -- "直接持有 struct+(不经过 MountableFS)" --> S3+```++## 3.2 数据流(三个核心命令)++```mermaid+sequenceDiagram+ participant U as User/Agent+ participant V as VikingFS (Python)+ participant B as RAGFSBindingClient+ participant G as GitService+ participant M as MountableFS+ participant O as ObjectStore+ participant R as RefStore++ Note over U,R: --- commit ---+ U->>V: commit(message, paths)+ V->>B: git_commit(account, branch, ...)+ B->>G: GitService::commit(req)+ G->>M: tree_directory / read (枚举+读 blob)+ M-->>G: 文件内容流+ G->>O: put(blob_oid, zlib)+ G->>O: put(tree_oid, zlib)+ G->>O: put(commit_oid, zlib)+ G->>R: cas_update(refs/heads/main, parent, new)+ R-->>G: ok / conflict+ G-->>B: CommitResponse+ B-->>V: dict+ V-->>U: commit_oid++ Note over U,R: --- show (只读) ---+ U->>V: show(ref, path)+ V->>B: git_show(account, ref, path)+ B->>G: GitService::show+ G->>R: read(refs/heads/main)+ G->>O: get(commit_oid) → tree_oid+ G->>O: get(tree_oid) → blob_oid+ G->>O: get(blob_oid)+ G-->>B: blob bytes+ B-->>V: bytes+ V-->>U: bytes++ Note over U,R: --- checkout (写回 VFS) ---+ U->>V: checkout(ref, paths)+ V->>B: git_checkout(account, ref, paths, dry_run)+ B->>G: GitService::checkout+ G->>O: 加载 commit → root tree → 递归列 (path, blob_oid)+ G->>M: stat / read 对比当前态+ G->>M: write / remove (走完整 VFS 语义)+ G-->>B: 差异报告+ B-->>V: dict+ V-->>U: applied / deleted / skipped+```++## 3.3 关键设计原则++> 💡 **Git 数据不进 viking 命名空间**+>+> Git 模块直接持有 `LocalFileSystem`/`S3Client` 实例,**不**通过 `MountableFS` 路由。Git 数据存到 `git/{account}/objects/...`,用户在 `viking://` 下看不到、也改不到。++> 💡 **LocalObjectStore 和 S3ObjectStore 直接调用 tokio::fs 和 Arc\<aws\_sdk\_s3::Client>, 不复用 LocalFileSystem/S3Client**+>+> LocalFileSystem/S3Client 是面向"用户文件树"的抽象,而 Git 后端是面向"内容寻址对象库"的存储,两者的语义需求不重叠。强行复用会导致更复杂的胶水代码。++***++# 4. Repo 边界与 Tree 布局++## 4.1 Tree 镜像 VikingFS 命名空间++由于 `viking_fs._uri_to_path` 已经定义了 `viking://X → /local/{account_id}/X` 的映射规则,我们让 Git 的 root tree 完全镜像 `/local/{account_id}/` 下的子目录结构。这样 tree path 与 viking URI 后缀一一对应,语义直观、无歧义。++## 4.2 路径剪枝(自动排除)++剪枝规则集中实现在 `crates/ragfs/src/git/enumerate.rs::prune_path`,在 `commit` 入口对 `paths=Some(...)` 与 `paths=None`(全量枚举)两条路径都生效:++| 类别 | 规则 | 理由 |+| ------------- | ------------------------------------------------------- | --------------------------------------------------------------- |+| 内部 scope / 目录 | 第一段命中 `_system` / `tasks` / `temp` / `queue` / `upload` | 与 `VikingFS._INTERNAL_NAMES` / `INTERNAL_SCOPES` 一致,均为运行时锁/系统状态 |+| 运行时锁文件 | 任意段以 `.path.ovlock` 开头 | VFS 内部锁,不应纳入版本 |+| 向量缓存目录 | 任意非叶段等于 `embedding_cache` | embedding 缓存为派生数据 |+| 向量索引文件 | 叶子文件以 `.faiss` 或 `.index` 结尾 | 纯计算产物,体积大且可重建 |++L0/L1 派生文件(`.abstract.md`、`.overview.md`、`.relations.json`)未命中任一剪枝规则,**会**纳入主线 commit。restore 时随源文件一起回滚,无需重新生成;Python 层在 `restore` 完成后按 `(written_paths, deleted_paths)` 精确触发 L0/L1/DETAIL 向量异步重建(`.relations.json` 不触发向量任务)。++## 4.3 单库多命名空间的优势++1. **原子跨 scope 快照**:一次 commit 可同时覆盖 `resources/docs` 和 `agent/skills`,对应"Agent 一次任务的所有产出"这种逻辑事务+2. **定向回滚**:restore 时可指定 `paths=["resources/docs/auth.md"]`,只回滚单个文件+3. **索引数据线性**:objects/refs 数量随账号线性,不随 resource 数量指数膨胀+4. **权限边界清晰**:account\_id 已经是天然的隔离单位,Git 仓库边界与现有权限模型完全对齐++***++# 5. 物理布局++## 5.1 Crate 目录结构++Git 模块作为 `crates/ragfs` 的子模块,与 `core/`、`plugins/`、`server/` 平级。新增文件全部位于 `crates/ragfs/src/git/` 下,Python binding 仅在 `crates/ragfs-python/src/lib.rs` 上追加方法,无新 crate。++```+crates/ragfs/src/+├── core/ # 既有(不动)+├── plugins/ # 既有(不动)+├── server/ # 既有(不动)+└── git/ # 新增+ ├── mod.rs # 模块入口 + 重导出+ ├── service.rs # GitService(commit/restore/show 主流程,均在此文件)+ ├── object_store.rs # ObjectStore trait+ ├── ref_store.rs # RefStore trait+ ├── tree_builder.rs # TreeEditor + flatten/lookup 工具+ ├── commit.rs # write_commit / Actor / 时间戳+ ├── enumerate.rs # 从 MountableFS 枚举 + prune_path 剪枝+ ├── util.rs # zlib 压缩/解压、ref 名校验、loose object 读写+ ├── types.rs # 请求/响应 DTO+ ├── error.rs # GitError / ObjectStoreError / RefStoreError(thiserror)+ ├── config.rs # GitConfig(serde)+ └── backends/+ ├── mod.rs+ ├── local.rs # LocalObjectStore / LocalRefStore(直接使用 tokio::fs)+ └── s3.rs # S3ObjectStore / S3RefStore(直接使用 aws_sdk_s3 + If-Match)++crates/ragfs-python/src/+└── lib.rs # 追加 git_commit / git_restore / git_show 方法++openviking/openviking/storage/+└── viking_fs.py # 追加 commit / restore / show / log + URI↔tree-path 工具+```++## 5.2 依赖增量++仅引入 gitoxide 中实现 commit/restore/show MVP 所需的最小子 crate 集合,通过 `crates/ragfs/Cargo.toml` 增量声明:++```toml+[dependencies]+# === Git (gitoxide) ===+gix-hash = "0.14" # ObjectId / Hash 抽象+gix-object = "0.42" # Blob/Tree/Commit 编解码 + tree::Editor+gix-actor = "0.31" # 作者/提交者签名(name ts tz)+gix-date = "0.8" # 时间戳格式化++# === Zlib 压缩 ===+flate2 = "1" # loose object zlib 编解码++# === S3 后端 ===+aws-sdk-s3 = ... # S3 API client(直接依赖,不复用 plugins/s3fs 内部封装)+aws-config = ...++[dev-dependencies]+tempfile = "3"+```++> 💡 **说明:** 不引入 `gitoxide` 顶层 crate,只挑选 commit/restore/show MVP 必需的子 crate;不引入 `gix-pack`(MVP 只用 loose object 格式)、不引入 `gix-protocol`(无 push/pull 需求)、不引入 `gix-worktree`(restore 通过 VFS 完成)。+>+> - 实际实现使用 `flate2` 直接做 zlib 编解码,而非 `gix-features`,以减少 gitoxide 依赖面。+> - ref 名校验由 `crates/ragfs/src/git/util.rs` 中自实现的 `validate_ref_name` 完成,未引入 `gix-validate`。+> - 并发模型测试(`loom`)与 fuzz 测试(`proptest`)在 MVP 阶段未引入,以单测 + 集成测试覆盖。++***++# 6. 核心 Trait 设计++## 6.1 ObjectStore++`ObjectStore` 是 Git 内容寻址存储的抽象,提供 blob/tree/commit 三类对象的存取。所有写入按 SHA-1 内容寻址,天然幂等(同样的字节 → 同样的 oid)。trait 必须 `Send + Sync + 'static`,以便在 Tokio 多线程运行时中跨任务共享。++```rust+// crates/ragfs/src/git/object_store.rs+use async_trait::async_trait;+use bytes::Bytes;+use gix_hash::ObjectId;++/// 内容寻址的 Git 对象存储抽象+/// put 必须幂等;get 不存在返回 NotFound;exists 不读取内容+#[async_trait]+pub trait ObjectStore: Send + Sync + 'static {+ /// 写入一个已 zlib 压缩的 loose object+ /// oid 必须等于 SHA-1(未压缩 header + payload)+ async fn put(+ &self,+ account: &str,+ oid: &ObjectId,+ zlib_body: Bytes,+ ) -> Result<(), ObjectStoreError>;++ /// 读取并 zlib 解压(返回 header + payload 的原始字节)+ async fn get(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> Result<Bytes, ObjectStoreError>;++ /// 仅检查存在性(HEAD/stat 优化,跳过内容传输)+ async fn exists(+ &self,+ account: &str,+ oid: &ObjectId,+ ) -> Result<bool, ObjectStoreError>;+}++#[derive(Debug, thiserror::Error)]+pub enum ObjectStoreError {+ #[error("object not found: {0}")]+ NotFound(ObjectId),+ #[error("backend io: {0}")]+ Io(#[from] std::io::Error),+ #[error("zlib decode: {0}")]+ Zlib(String),+ #[error("oid mismatch: expected {expected}, got {actual}")]+ OidMismatch { expected: ObjectId, actual: ObjectId },+ #[error("backend error: {0}")]+ Backend(String),+}+```++> ℹ️ **说明:** 物理路径布局由各实现自行决定(local 走 fanout 目录,s3 走 key prefix),trait 层不暴露物理路径,只暴露逻辑寻址。++## 6.2 RefStore++`RefStore` 是分支/标签的命名引用存储,核心是 **CAS(Compare-And-Swap)** 更新原语 — 这是 Git 一致性的基石。CAS 保证"两个并发 commit 先到先得,后到的看到 `Conflict` 并需要重试或 rebase",避免静默覆盖。++```rust+// crates/ragfs/src/git/ref_store.rs+use async_trait::async_trait;+use gix_hash::ObjectId;++#[async_trait]+pub trait RefStore: Send + Sync + 'static {+ /// 读取 ref 的当前值;不存在返回 NotFound+ async fn read(+ &self,+ account: &str,+ ref_name: &str,+ ) -> Result<ObjectId, RefStoreError>;++ /// Compare-And-Swap 更新:仅当当前值 == expected 时才写入 new+ /// expected = None 表示"仅当 ref 不存在时创建"+ async fn cas_update(+ &self,+ account: &str,+ ref_name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<(), RefStoreError>;++ /// 列出 account 下的所有 refs(用于 log / branch 列表)+ async fn list(+ &self,+ account: &str,+ prefix: &str,+ ) -> Result<Vec<(String, ObjectId)>, RefStoreError>;+}++#[derive(Debug, thiserror::Error)]+pub enum RefStoreError {+ #[error("ref not found: {0}")]+ NotFound(String),+ #[error("CAS conflict: expected {expected:?}, actual {actual:?}")]+ Conflict {+ expected: Option<ObjectId>,+ actual: Option<ObjectId>,+ },+ #[error("invalid ref name: {0}")]+ InvalidName(String),+ #[error("backend io: {0}")]+ Io(#[from] std::io::Error),+ #[error("backend: {0}")]+ Backend(String),+}+```++> ⚠️ **注意:** ref 名必须经 `crate::git::util::validate_ref_name(...)` 校验,拒绝 `..`、空字符、特殊保留字等,避免路径穿越和注入(实现位于 `git/util.rs`,未引入 `gix-validate`)。++## 6.3 命名约定++| 类别 | 路径模板 | 说明 |+| ----------- | --------------------------------------- | -------------------------------------------------------- |+| Object | `{root}/{account}/objects/{aa}/{bb...}` | Git 标准 fanout(前 2 hex 为目录,后 38 hex 为文件名),便于分布式存储 list 优化 |+| Ref (heads) | `{root}/{account}/refs/heads/{branch}` | 文件内容 = 40 hex 字符 + `\n` |+| HEAD | `{root}/{account}/HEAD` | 内容 = `ref: refs/heads/main\n` |+| Packed-refs | (不实现) | MVP 全部 loose,后续如 ref 数量爆炸再补 pack |++***++# 7. 后端实现++## 7.1 LocalObjectStore / LocalRefStore++**LocalObjectStore** 直接调用 `tokio::fs`(不经 MountableFS、也不复用 `LocalFileSystem`),把 Git 对象写入本地磁盘的 `{base_dir}/{account}/objects/{aa}/{bb...}`。**LocalRefStore** 使用进程内的 `DashMap<(account, ref_name), Arc<Mutex<()>>>` 串行化同 ref 的 CAS,叠加 `tempfile + rename(2)` 的原子重命名,覆盖同进程并发场景。++> **当前实现限制:** MVP 仅做了进程内 Mutex,**未叠加** `flock` 跨进程锁。生产部署若存在同 host 多进程同时写同一账号的场景,需要在后续版本补 `flock`。++```rust+// crates/ragfs/src/git/backends/local.rs (节选)+pub struct LocalObjectStore {+ base_dir: PathBuf, // e.g. /data/openviking/git+}++#[async_trait]+impl ObjectStore for LocalObjectStore {+ async fn put(&self, account: &str, oid: &ObjectId, body: Bytes) -> Result<()> {+ let hex = oid.to_hex().to_string();+ let path = self.base_dir+ .join(account).join("objects")+ .join(&hex[..2]).join(&hex[2..]);+ // 内容寻址 → 已存在则跳过(幂等)+ if tokio::fs::try_exists(&path).await? { return Ok(()); }+ tokio::fs::create_dir_all(path.parent().unwrap()).await?;+ // 写临时文件 + rename 保证原子性+ let tmp = path.with_extension("tmp");+ tokio::fs::write(&tmp, &body).await?;+ tokio::fs::rename(&tmp, &path).await?;+ Ok(())+ }+ // get / exists 略+}++pub struct LocalRefStore {+ base_dir: PathBuf,+ // 进程内串行化 CAS,key = (account, ref_name)+ locks: dashmap::DashMap<(String, String), Arc<Mutex<()>>>,+}++#[async_trait]+impl RefStore for LocalRefStore {+ async fn cas_update(+ &self,+ account: &str,+ name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<()> {+ validate_ref_name(name)?; // util.rs 自实现+ let lock = self.locks+ .entry((account.into(), name.into()))+ .or_default().clone();+ let _guard = lock.lock().await;+ let path = self.ref_path(account, name);+ let actual = read_ref_opt(&path).await?;+ if actual != expected {+ return Err(RefStoreError::Conflict { expected, actual });+ }+ let tmp = path.with_extension("tmp");+ tokio::fs::write(&tmp, format!("{}\n", new.to_hex())).await?;+ // rename 保证 crash-consistency+ tokio::fs::rename(&tmp, &path).await?;+ Ok(())+ }+}+```++## 7.2 S3ObjectStore / S3RefStore++**S3ObjectStore** 直接持有一个 `Arc<aws_sdk_s3::Client>`(MVP 不复用 `plugins::s3fs::S3Client`,以解耦 git 模块与 plugin 体系),将 object 存为 `{prefix}/{account}/objects/{aa}/{bb...}`。由于内容寻址,`put` 用 `If-None-Match: *` 头实现幂等"仅首次写入"。**S3RefStore** 用 `If-Match: "{etag}"` 实现 CAS,先 `GET` 拿当前值与 ETag,再用 `PUT` 条件写。++> **CAS 模式:** `CasMode::Native` 已实现并默认启用;`CasMode::RedisLock` 仅作为枚举占位,**实际尚未实现**,调用会直接返回 `RefStoreError::Backend("RedisLock CAS mode not yet implemented")`。++```rust+// crates/ragfs/src/git/backends/s3.rs (节选)+pub struct S3RefStore {+ client: Arc<aws_sdk_s3::Client>,+ bucket: String,+ prefix: String,+ cas_mode: CasMode, // Native | RedisLock(占位,未实现)+}++#[async_trait]+impl RefStore for S3RefStore {+ async fn cas_update(+ &self,+ account: &str,+ name: &str,+ expected: Option<ObjectId>,+ new: ObjectId,+ ) -> Result<()> {+ validate_ref_name(name)?;+ match self.cas_mode {+ CasMode::Native => {+ // 1. GET 当前 body 与 ETag+ let current = self.read_ref_opt(account, name).await?;+ let (current_oid, current_etag) = match current {+ Some((oid, etag)) => (Some(oid), etag),+ None => (None, None),+ };+ if current_oid != expected {+ return Err(RefStoreError::Conflict {+ expected, actual: current_oid,+ });+ }+ // 2. 条件 PUT+ let body = format!("{}\n", new.to_hex());+ let put = self.client.put_object()+ .bucket(&self.bucket).key(&self.ref_key(account, name))+ .body(body.into_bytes().into());+ let put = match (current_etag, expected) {+ (Some(etag), Some(_)) => put.if_match(etag),+ (None, None) => put.if_none_match("*"),+ _ => return Err(RefStoreError::Conflict {+ expected, actual: current_oid,+ }),+ };+ // 412 → Conflict;其他 → Backend+ map_precondition_failed(put.send().await, expected, current_oid)+ }+ CasMode::RedisLock => Err(RefStoreError::Backend(+ "RedisLock CAS mode not yet implemented".into(),+ )),+ }+ }+}+```++> ⚠️ **S3 CAS 兼容性提示:** AWS S3 自 2024 年起支持 `If-Match` / `If-None-Match` 条件写;TOS / OSS 实现情况需在选型时验证。若某后端不支持原生 CAS,需退化为"分布式锁 + GET-then-PUT"模式;`RedisLock` 模式已在配置/枚举中预留,但实现待补。++***++# 8. GitService 主流程++## 8.1 commit 完整实现++commit 主流程:**枚举 → 读 blob → 构建 tree → 构建 commit → CAS 更新 ref**。所有 ObjectStore 写入按账号粒度幂等(同 oid 多次 put 安全),tree 写入由 `TreeEditor` 自底向上完成。tree 未变 → 不创建空 commit(no-op 优化)。绝大多数 commit 场景下,被调用方声明为 "改动" 的文件里仍有大量未真正修改,需要通过三级 fast path 层层过滤,保证只有真正变化的字节才进入 streaming hash 与 blob 写入。++| 层级 | 触发条件 | 节省的开销 | 实现位置 |+| ------------------------------ | --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| **Fast Path 1**: Stat 索引复用 oid | 文件 (size, mtime\_ns) 与 prev\_index 完全一致 | 跳过 `vfs.read` + sha1 hash | **已实现**(`IndexStore` trait + `LocalIndexStore`/`S3IndexStore`,`CommitIndex` 与 `parent_oid` 绑定,索引 miss/decode 错误/parent 不匹配 → 静默回退 slow path;通过 `git.tuning.commit_index_enabled` 关闭) |+| **Fast Path 2**: Tree 子树原样保留 | 子树下所有路径都没 upsert/remove | 跳过子树重 hash + 新 tree object 写入 | **已实现**(`TreeEditor::from_tree` 惰性加载 root,未被 upsert/remove/upsert\_subtree 触及的子树连读取+zlib 解压都省掉,由 `write_subtree` 的 `None` 分支原样复用其 OID) |+| **Fast Path 3**: Blob CAS 去重 | 算出的 oid 在 object\_store 已存在 | 跳过 zlib 压缩 + put\_blob (本地写盘 / S3 PUT) | **已实现**(slow path 写 blob 前在 service 层调用 `object_store.exists` 预检,命中则跳过 zlib 压缩与 `put`;范围严格限定 blob,tree/commit 不预检;通过 `git.tuning.blob_exists_precheck_enabled` 关闭) |++```rust+// crates/ragfs/src/git/service.rs ::commit (节选)+pub async fn commit(&self, req: CommitRequest) -> Result<CommitResponse> {+ let CommitRequest {+ account, branch, message, paths, author_name, author_email,+ } = req;++ // 1. 解析当前 HEAD,加载 prev_tree(若 ref 不存在则空 tree)+ let prev_head = self.resolve_ref(&account, &branch).await.ok();+ let prev_tree = match prev_head {+ Some(oid) => self.load_commit(&account, &oid).await?.tree,+ None => empty_tree_oid(),+ };+ let mut editor = TreeEditor::from_tree(+ &self.object_store, &account, prev_tree,+ ).await?;+ let mut changed = 0usize;++ // 2. 候选路径:paths=Some → 经 prune_path 过滤后的清单;paths=None → enumerate::collect_all 全量+ let candidates = match &paths {+ Some(ps) => ps.iter().filter_map(prune_path).collect(),+ None => enumerate::collect_all(&self.vfs, &account).await?,+ };++ for path in candidates {+ match self.vfs.stat(&account_path(&account, &path)).await {+ Ok(_) => {+ // 读全量 + streaming hash + 写 blob(无 Fast Path 1/3)+ let bytes = self.vfs.read(&account_path(&account, &path)).await?;+ let oid = sha1_blob_streaming(&bytes);+ self.write_object(&account, &oid, &bytes).await?; // 幂等+ editor.upsert(&path, oid)?;+ changed += 1;+ }+ Err(e) if is_not_found(&e) => {+ // 文件被删 → 从 tree 中移除+ editor.remove(&path)?;+ changed += 1;+ }+ Err(e) => return Err(e.into()),+ }+ }++ // 3. 无任何变化 → noop+ if changed == 0 {+ return Ok(CommitResponse::Noop {+ commit_oid: prev_head.unwrap_or_default(),+ });+ }++ // 4. 写 tree + commit+ let new_tree = editor.write(&self.object_store, &account).await?;+ let commit_oid = write_commit(&self.object_store, &account, CommitObject {+ tree: new_tree,+ parents: prev_head.into_iter().collect(),+ author: Actor::now(&author_name, &author_email),+ committer: Actor::now(&author_name, &author_email),+ message: message.into(),+ }).await?;++ // 5. CAS 更新 ref;失败 → ConcurrentCommit 直接上抛+ // 注意:当前实现中 commit() 内部不做 retry,由调用方决定如何处理冲突。+ self.ref_store.cas_update(+ &account, &format!("refs/heads/{}", branch),+ prev_head, commit_oid,+ ).await?;++ Ok(CommitResponse::Created { commit_oid, changed })+}+```++> **关于 retry:** 当前实现中 `commit()` 内部 **不包含 CAS 重试循环**(代码中明确注释 `// There is intentionally no retry loop inside commit().`)。冲突直接以 `ConcurrentCommit` 上抛,由 Python 层或上游业务决定重试策略;这与 §11.3 旧版描述的"内部最多重试 3 次"不一致,以本节为准。++## 8.2 restore 完整实现++restore 主流程:**解析目标 commit → 提取该 commit 中 project\_dir 子树 → 与当前 HEAD 中同路径子树 diff → 通过 MountableFS.write/rm 回写 → 删除回写后空目录 → 以当前 HEAD 为 parent 生成新 commit → CAS 更新 ref → 把受影响路径返回给调用方**。`dry_run` 模式只计算差异不写,用于预检。++向量索引重建在 service 层**不直接触发**,而是通过把 `written_paths` / `deleted_paths` 放到 `RestoreResponse::Applied` 中返回,Python 层(`VikingFS.restore`)再调度 `ReindexExecutor`。++关键差异:与 git checkout 不同,本接口**不移动分支指针到旧 commit**,而是把"旧内容"作为新 commit 的工作树内容,正向写入。新 commit 的 parent 是当前 HEAD,不是目标 commit,这保证了:(1) HEAD 单调前进;(2) 非 `project_dir` 路径自动保留 HEAD 的最新内容,无需特殊处理;(3) restore 本身可以被再次 restore (因为它就是一个普通 commit)。++```rust+pub async fn restore(&self, req: RestoreRequest) -> Result<RestoreResponse> {+ let RestoreRequest {+ account, branch, project_dir, source_commit, dry_run, message,+ author_name, author_email,+ } = req;++ // 0. 校验 project_dir(非空、不含 ..、不命中 prune 规则)+ validate_project_dir(&project_dir)?;++ // 1. 解析两端 commit+ let source_oid = self.resolve_ref(&account, &source_commit).await?;+ let source = self.load_commit(&account, &source_oid).await?;+ let head_oid = self.resolve_ref(&account, &branch).await?; // 必须已有 HEAD+ let head = self.load_commit(&account, &head_oid).await?;++ // 2. 在两棵 tree 中分别"截取" project_dir 子树+ // source 没有该子目录 → 视为空树(等价于把整个目录删掉)+ let source_subtree = tree_builder::subtree(...).await?+ .unwrap_or(empty_tree_oid());+ let head_subtree = tree_builder::subtree(...).await?+ .unwrap_or(empty_tree_oid());++ // 3. 子树之间 diff,得到三类操作(只限 project_dir 范围内)+ let target_entries = flatten(&self.object_store, &account, source_subtree).await?;+ let current_entries = flatten(&self.object_store, &account, head_subtree).await?;+ let diff = compute_subtree_diff(&target_entries, ¤t_entries);++ if dry_run {+ return Ok(RestoreResponse::DryRun { diff, source_oid, head_oid });+ }+ if diff.is_empty() {+ return Ok(RestoreResponse::Noop { head: head_oid, source: source_oid });+ }++ // 4. 并发回写 VFS:路径要带上 project_dir 前缀+ // 走完整 viking_fs.write/rm,触发现有 lock、加密+ let prefixed = |p: &str| format!("{}/{}", project_dir.trim_end_matches('/'), p);+ let written_paths: Vec<String> = stream::iter(diff.to_write)+ .map(|(path, blob_oid)| async move {+ let body = self.read_blob(&account, &blob_oid).await?;+ self.vfs.write(&account_path(&account, &prefixed(&path)), body).await?;+ Ok::<_, GitError>(prefixed(&path))+ })+ .buffer_unordered(32) // 当前实现硬编码 32,未读取 git.tuning.restore_concurrency+ .try_collect().await?;+ let deleted_paths: Vec<String> = stream::iter(diff.to_delete)+ .map(|path| {+ let p = prefixed(&path);+ async move {+ // 幂等删除:NotFound 视为成功,允许 restore 在已被并发删除的路径上完成+ match self.vfs.rm(&account_path(&account, &p)).await {+ Ok(()) => Ok(p),+ Err(e) if is_not_found(&e) => Ok(p),+ Err(e) => Err(e.into()),+ }+ }+ })+ .buffer_unordered(32)+ .try_collect().await?;++ // 6b. 删除空目录:沿被删路径的祖先链向上 rmdir,直到第一个非空目录或 project_dir 边界+ // (gix tree 不存空目录,而 VFS 写到本地后会留下空 dir,造成 ls 不一致)+ self.prune_empty_dirs(&account, &project_dir, &deleted_paths).await?;++ // 5. 在 head.tree 之上做增量编辑:+ // 把 project_dir 子树整体替换为 source_subtree。+ // 非 project_dir 路径原样保留 head 中的 tree_oid。+ let mut editor = TreeEditor::from_tree(&self.object_store, &account, head.tree).await?;+ editor.upsert_subtree(&project_dir, source_subtree)?;+ let new_tree = editor.write(&self.object_store, &account).await?;++ // 6. 构造新 commit:parent = 当前 HEAD(不是 source_oid!)+ let new_commit_oid = write_commit(&self.object_store, &account, CommitObject {+ tree: new_tree,+ parents: vec![head_oid], // ← 关键:HEAD 单向前进+ author: Actor::now(&author_name, &author_email),+ committer: Actor::now(&author_name, &author_email),+ message: message.unwrap_or_else(|| format!(+ "restore {} from {}", project_dir, &source_oid.to_hex()[..12],+ )),+ }).await?;++ // 7. CAS 更新 ref:expect=head_oid, new=new_commit_oid+ // 若期间有别的 commit 进入 → ConcurrentCommit,调用方按提示重试+ self.ref_store.cas_update(+ &account, &format!("refs/heads/{}", branch),+ Some(head_oid), new_commit_oid,+ ).await?;++ Ok(RestoreResponse::Applied {+ new_commit_oid,+ source_commit: source_oid,+ parent_commit: head_oid,+ // 计数 + 受影响路径(供上层精确触发向量重建)+ written: written_paths.len(),+ deleted: deleted_paths.len(),+ unchanged: diff.unchanged.len(),+ written_paths,+ deleted_paths,+ })+}+```++> 当前实现相对早期设计的差异+>+> - **空目录清理(步骤 6b)**:删除完文件后会沿祖先链 rmdir 至 `project_dir` 或第一个非空目录,避免 VFS 残留空目录。+> - **幂等删除**:`vfs.rm` 返回 NotFound 视为成功,使 restore 可以在已被并发清理的路径上继续推进。+> - **written\_paths / deleted\_paths**:`Applied` 响应除了 `written/deleted` 计数外,还返回**全量受影响路径(已加 project\_dir 前缀)**;Python 层按 marker / 源文件 / `.relations.json` 分类,精确触发 L0/L1/DETAIL 向量更新,不再依赖广义的 `_trigger_vector_rebuild(paths)`。+> - **没有 commit\_index 刷新**:对应 §8.1 的 Fast Path 1 未实现,restore 末尾也无须刷新 index。+> - **回写并发度**:当前硬编码 `buffer_unordered(32)`,**尚未**读取 `git.tuning.restore_concurrency` 配置项。+>+> ✅ **推荐:** 生产环境调用前先以 `dry_run=true` 跑一遍取得差异列表,再让用户确认,避免误覆盖未提交的本地变更。++## 8.3 show 完整实现++show 是**纯读路径**,无任何 VFS 写入或 ref 变更,易于实现与验证。支持两种模式:`path=None` 返回 commit 元信息(用于 log 列表);`path=Some(p)` 返回该 path 的 blob 字节(零拷贝 `Bytes` 切片)。++```rust+pub async fn show(&self, req: ShowRequest) -> Result<ShowResponse> {+ let ShowRequest { account, target_ref, path } = req;++ // 1. ref 解析:依次尝试+ // a. 40-hex commit_oid → 直接解析+ // b. 4..=39 hex 的缩写 oid → 沿 HEAD 父链回溯,找到唯一前缀匹配的 commit+ // (歧义返回 AmbiguousOid;无匹配返回 OidPrefixNotFound)+ // c. branch 名(如 "main") → 加前缀 refs/heads/{branch}+ // d. 全路径 refs/heads/xxx → 透传+ let commit_oid = self.resolve_ref(&account, &target_ref).await?;+ let commit = self.load_commit(&account, &commit_oid).await?;++ match path {+ // 模式 A:返回 commit 元信息(log 用)+ None => Ok(ShowResponse::Commit {+ oid: commit_oid,+ tree: commit.tree,+ parents: commit.parents,+ author: commit.author.into(),+ committer: commit.committer.into(),+ message: commit.message.to_string(),+ }),++ // 模式 B:返回该 path 的 blob 字节+ Some(p) => {+ // 按 / 拆分,在 tree 上逐层递归;+ // - path 命中目录 → PathIsDirectory(p)+ // - path 完全无对应 → PathNotFound(p)+ let blob_oid = tree_builder::lookup(+ &self.object_store, &account, commit.tree, &p,+ ).await?;++ let blob_full = self.load_blob(&account, &blob_oid).await?;+ // 去掉 "blob {len}\0" header,使用 Bytes::slice 零拷贝返回 payload+ let payload = strip_object_header(blob_full)?;+ Ok(ShowResponse::Blob {+ oid: blob_oid,+ size: payload.len() as u64,+ bytes: payload,+ })+ }+ }+}+```++***++# 9. Python Binding 与 VikingFS 集成++## 9.1 PyO3 binding 新增方法++在现有 `RAGFSBindingClient`(`crates/ragfs-python/src/lib.rs`)上追加三个 `#[pymethods]`。模式与 `ls/read/write` 一致:用 `py_detach_blocking` 释放 GIL,在 Tokio runtime 内调 `GitService`,返回结果序列化为 `PyDict`。++```rust+// crates/ragfs-python/src/lib.rs (追加)+#[pymethods]+impl RAGFSBindingClient {+ /// 提交一次快照+ /// kwargs: account, branch, message, paths(Option<Vec<String>>),+ /// author_name, author_email+ /// returns: {"commit_oid": str, "result": "created" | "noop"}+ fn git_commit(&self, py: Python<'_>, kwargs: &PyDict) -> PyResult<PyObject> {+ let req = parse_commit_request(kwargs)?;+ let svc = self.git_service()?; // FeatureDisabled 时返回 PyErr+ py_detach_blocking(py, || {+ self.runtime.block_on(svc.commit(req))+ .map_err(map_git_error)+ }).map(|r| commit_response_to_pydict(py, r))+ }++ /// 定向恢复某个 project 目录,正向生成新 commit+ /// kwargs: account, branch(默认 "main"), project_dir, source_commit,+ /// dry_run(bool=false), message(Option<String>),+ /// author_name, author_email+ /// returns:+ /// Applied: {"new_commit_oid": str, "source_commit": str, "parent_commit": str,+ /// "written": int, "deleted": int, "unchanged": int}+ /// Noop: {"noop": true, "head": str, "source": str}+ /// DryRun: {"dry_run": true, "diff": {...}, "head": str, "source": str}+ fn git_restore(&self, py: Python<'_>, kwargs: &PyDict) -> PyResult<PyObject> {+ let req = parse_restore_request(kwargs)?;+ let svc = self.git_service()?;+ py_detach_blocking(py, || self.runtime.block_on(svc.restore(req))+ .map_err(map_git_error))+ .map(|r| restore_response_to_pydict(py, r))+ }++ /// 读取 ref / commit / blob+ /// kwargs: account, target_ref, path(Option)+ /// returns:+ /// path=None: {"oid","tree","parents","author","committer","message"}+ /// path=str: {"oid","size","bytes": PyBytes}+ fn git_show(&self, py: Python<'_>, kwargs: &PyDict) -> PyResult<PyObject> {+ let req = parse_show_request(kwargs)?;+ let svc = self.git_service()?;+ py_detach_blocking(py, || {+ self.runtime.block_on(svc.show(req))+ .map_err(map_git_error)+ }).map(|r| show_response_to_pydict(py, r))+ }+}++/// GitError → Python 异常映射(在 openviking 侧定义对应异常类)+fn map_git_error(e: GitError) -> PyErr {+ match e {+ GitError::FeatureDisabled => PyRuntimeError::new_err("git feature disabled"),+ GitError::ConcurrentCommit => PyValueError::new_err("concurrent commit conflict"),+ GitError::PathNotFound(p) => PyFileNotFoundError::new_err(p),+ GitError::RefNotFound(r) => PyFileNotFoundError::new_err(r),+ other => PyRuntimeError::new_err(other.to_string()),+ }+}+```++## 9.2 Python 侧 VikingFS 新增方法++在 `openviking/openviking/storage/viking_fs.py` 的 `VikingFS` 类上追加 4 个公开方法。Python 调用方使用 `viking://` URI,内部经 `_uri_to_tree_path` 转换为账号内 tree 路径后再传给 binding。++```python+# openviking/storage/viking_fs.py (追加)+class VikingFS:+ # 已有: read / write / rm / ls / mv / mkdir ...++ async def commit(+ self,+ *,+ message: str,+ paths: list[str] | None = None, # viking://... URIs+ branch: str = "main",+ author_name: str | None = None,+ author_email: str | None = None,+ ) -> dict:+ """提交一次跨 scope 快照。返回 {commit_oid, result}."""+ account = self._current_account()+ tree_paths = [self._uri_to_tree_path(p) for p in (paths or [])]+ return await self._async_client.run(+ "git_commit",+ account=account,+ branch=branch,+ message=message,+ paths=tree_paths or None,+ author_name=author_name or self._default_author_name(),+ author_email=author_email or self._default_author_email(),+ )++ async def restore(+ self,+ *,+ project_dir: str, # viking://resources/proj_a/ 或 "resources/proj_a"+ source_commit: str, # 40-hex / branch / tag+ branch: str = "main",+ dry_run: bool = False,+ message: str | None = None,+ author_name: str | None = None,+ author_email: str | None = None,+ ) -> dict:+ """将 project_dir 恢复到 source_commit 状态,生成一个新 commit。++ 语义等价于 git restore --source=<source_commit> --worktree --staged+ <project_dir>/ && git commit。HEAD 单调前进,不会回退。+ """+ account = self._current_account()+ tree_dir = self._uri_to_tree_path(project_dir).rstrip("/")+ result = await self._async_client.run(+ "git_restore",+ account=account, branch=branch,+ project_dir=tree_dir, source_commit=source_commit,+ dry_run=dry_run, message=message,+ author_name=author_name or self._default_author_name(),+ author_email=author_email or self._default_author_email(),+ )+ if dry_run or result.get("noop"):+ return result++ # 增量向量更新:只对受影响的源文件,逐个 vectors_only 重算。+ # L0/L1 派生文件已随源文件一起从 git 回写到 VFS,不需要重新生成。+ from openviking.service.reindex_executor import ReindexExecutor+ executor = ReindexExecutor()+ ctx = self._current_request_context()+ for affected_path in result.get("affected_files", []):+ affected_uri = self._tree_path_to_uri(affected_path)+ if self._is_derived_file(affected_uri):+ continue+ asyncio.create_task(executor.execute(+ uri=affected_uri, mode="vectors_only",+ wait=False, ctx=ctx,+ ))+ return result++ async def show(+ self,+ target_ref: str,+ *,+ path: str | None = None,+ ) -> dict | bytes:+ """path=None → commit 元信息;path=str → blob 字节。"""+ account = self._current_account()+ tree_path = self._uri_to_tree_path(path) if path else None+ resp = await self._async_client.run(+ "git_show",+ account=account,+ target_ref=target_ref,+ path=tree_path,+ )+ if "bytes" in resp:+ return resp["bytes"]+ return resp++ async def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> list[dict]:+ """便捷封装:沿 parent 链反向遍历 commit。"""+ account = self._current_account()+ head = await self._async_client.run(+ "git_show", account=account, target_ref=branch, path=None,+ )+ result, current = [head], head.get("parents", [])+ while current and len(result) < limit:+ parent_oid = current[0]+ commit = await self._async_client.run(+ "git_show", account=account, target_ref=parent_oid, path=None,+ )+ result.append(commit)+ current = commit.get("parents", [])+ return result++ # --- 工具方法 ---+ def _uri_to_tree_path(self, uri: str) -> str:+ """viking://resources/a.md → 'resources/a.md'+ (去掉 viking:// 前缀,保留 scope 段作为 tree 一级目录)"""+ parsed = VikingURI.parse(uri)+ if parsed.scope in INTERNAL_SCOPES:+ raise ValueError(f"internal scope not versioned: {parsed.scope}")+ return f"{parsed.scope}/{parsed.relative_path}"++ async def _trigger_vector_rebuild(+ self, account: str, paths: list[str]+ ) -> None:+ """restore 后异步触发向量索引重建。+ 实现可对接现有的 watcher / 任务队列;失败不影响 restore 结果。"""+ try:+ await self._vector_service.rebuild(account, paths)+ except Exception:+ logger.exception("vector rebuild failed for %s", account)+```++***++# 10. 配置规范++## 10.1 与 resources 对称的配置布局++配置位于现有 RAGFS 配置文件的 `[git]` 段,布局与 `[plugins.localfs_resources]` / `[plugins.s3fs_resources]` 完全对称,便于运维心智复用。`enabled = false` 时 binding 方法返回 `FeatureDisabled`,不影响现有 VFS。++```toml+# ragfs.toml 新增 [git] 段+[git]+enabled = true+backend = "local" # "local" | "s3"+default_branch = "main"+author_name = "openviking-bot" # commit 默认作者+author_email = "[email protected]"++# 本地后端+[git.local]+base_dir = "/data/openviking/git" # objects/refs 存储根++# 远程后端(与 plugins.s3fs_resources 配置同构)+[git.s3]+bucket = "openviking-prod"+prefix = ".ovgit" # 全部 key = {prefix}/{account}/...+region = "us-east-1"+endpoint = "https://s3.amazonaws.com"+access_key_env = "OV_S3_AK" # 从环境变量读+secret_key_env = "OV_S3_SK"+cas_mode = "native" # "native"(If-Match):当前唯一支持的模式+use_path_style = true # path-style addressing(MinIO/LocalStack/TOS 默认开)++# 高级调优(字段已在 config 中定义,但 MVP 部分尚未生效)+[git.tuning]+upload_concurrency = 64 # ⚠️ 当前未读取:commit blob 上传现为串行+restore_concurrency = 32 # ⚠️ 当前未读取:restore 回写并发度硬编码 32+ref_cas_max_retry = 3 # ⚠️ 当前未读取:commit 内部不做重试(见 §11.3)+ref_cas_backoff_ms = 50 # ⚠️ 当前未读取+commit_index_enabled = true # Fast Path 1 总开关(默认 true);关闭后强制走 slow path,适合测试 / mtime 不可靠环境+```++## 10.2 切换本地↔远程++| 维度 | local → s3 改动 |+| ---------- | ----------------------------------------------------- |+| 配置文件 | `backend = "local"` → `backend = "s3"`;填 `[git.s3]` 块 |+| Service 代码 | 无 |+| Python 调用方 | 无 |+| 数据迁移 | 一次性脚本:本地 `{base_dir}` 全量上传至 S3 key prefix(保持目录结构) |++> 💡 从本地切到远程的全部成本 = 修改 `backend = "local"` → `backend = "s3"` + 填 `[git.s3]` 块。Service 代码、Python 调用方完全无感。这与 resources 目录"`plugins.localfs_resources` ↔ `plugins.s3fs_resources`"的切换体验完全对称。++***++# 11. 并发与一致性++## 11.1 写并发模型++| 层次 | 并发原语 | 说明 |+| --------- | ------------------------ | -------------------------------- |+| Blob 上传 | `buffer_unordered(64)` | 内容寻址,天然幂等;同 oid 多次 put 安全 |+| Tree 写入 | 串行(`Editor::write` 自底向上) | 同 oid 幂等,但顺序必须自底向上 |+| Commit 写入 | 串行,最后一步 | 同 oid 幂等 |+| Ref 更新 | CAS | 本地: 进程锁 + rename(2);S3: If-Match |++## 11.2 并发冲突处理++```mermaid+flowchart LR+ A[Client A: commit] --> A1[Read ref+= parent_a]+ B[Client B: commit] --> B1[Read ref+= parent_b]+ A1 --> A2[Build tree A]+ B1 --> B2[Build tree B]+ A2 --> A3[CAS update+expected=parent_a]+ B2 --> B3[CAS update+expected=parent_b]+ A3 --> OK1[OK new=commit_a]+ B3 --> FAIL[CasConflict+current=commit_a]+ FAIL --> RETRY{重试?}+ RETRY -- yes --> B1+ RETRY -- no --> ERR[返回 409+给上层]+```++## 11.3 重试策略++- **幂等部分(blob/tree/commit 写)**: 同 oid 多次 put 安全;后端层面通过 `If-None-Match: *`(S3)与 `try_exists`(local)短路重复写;service 层不额外做 retry。+- **CAS 冲突**: **当前实现** GitService::commit/restore **内部不做自动重试,直接以 GitError::ConcurrentCommit 上抛给 Python 层,由调用方决定是否 re-read parent 重建 tree 重新提交。git.tuning.ref\_cas\_max\_retry / ref\_cas\_backoff\_ms 配置项已在 GitTuningConfig 中定义但**尚未在代码中读取\*\*,后续接入。+- **跨账号**: 不同 account\_id 的 ref 路径不同,天然无冲突,可完全并行++***++# 12. 安全与隔离++## 12.1 账号隔离++- Git 数据路径全部以 `{account_id}` 为顶层前缀,与现有 `/local/{account_id}/` 隔离模型完全一致+- `GitService` 所有方法的第一个参数都是 `account_id`,binding 层从 `RequestContext.account_id` 注入,不允许跨账号访问+- Path 解析时必须经过 `validate_account_id`(白名单字符集 + 长度),防止 `../` 注入++## 12.2 加密++> 💡 **重要:** 现有 `viking_fs.write` 在写入前会调 `_encrypt_content`。**commit 时不应再次加密**——blob 内容 = 当前 VFS 已加密内容,Git 是对密文做版本管理。restore 写回时走 `viking_fs.write`,会再次"加密"——这里需要绕过(或保持密文不变):restore 路径走 `MountableFS.write` 而非 `viking_fs.write`,避免双重加密;或为 `viking_fs.write` 增加 `raw=True` 参数,restore 调用时传入。++## 12.3 资源限制++| 维度 | 限制 | 措施 | 当前状态 |+| ------------ | -------------------------------- | ------------------------------------ | ------------------------------------------------ |+| 单 blob 大小 | ≤ 100MB | commit 前 stat 检查,超限报错 | **未实现**(`GitError::BlobTooLarge` 已定义,但无运行时检查) |+| 单 commit 文件数 | ≤ 50000 | enumerate 阶段提前拒绝 | **未实现**(`GitError::TooManyFiles` 已定义,但无运行时检查) |+| 账号 Git 容量 | 由 quota 系统单独管控 | 放在 `[git.quota]`,首版默认 10GB | **未实现**(配置块未引入) |+| restore 并发 | 同子树串行,同一 account\_id 全量 restore 互斥 | `VikingFS.restore` 用 `LockContext` 树锁包裹 writeback:scoped restore 锁 `project_dir`,全量 restore 锁账号根;防止 VFS 写竞态 | **已实现**(写回阶段加锁;后台 reindex 在锁释放后调度,冲突映射为 `ResourceBusyError`) |+| 账号 ID 校验 | 白名单字符集 + 长度,防 `../` 注入 | `validate_account_id` 在 binding 入口拒绝 | **未实现**(`GitError::InvalidAccountId` 已定义,但无校验代码) |++***++# 13. 错误处理++## 13.1 错误分类++顶层错误类型为 `GitError`(`crates/ragfs/src/git/error.rs`),按可恢复性与归属分组:++| 类别 | Variant | 说明 |+| --------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |+| 后端透传 | `ObjectStore(ObjectStoreError)`、`RefStore(RefStoreError)`、`Vfs(...)` | 来自存储后端 / VFS |+| 路径校验 | `PathNotFound(String)`、`PathIsDirectory(String)`、`InvalidProjectDir(String)` | show / restore 入参校验 |+| Tree 内容缺失 | `SubtreeNotFoundInCommit { commit, path }` | restore 时 source 中缺失目标子树(已通过空树语义包装,正常路径不抛出) |+| Ref 解析 | `OidPrefixNotFound(String)`、`AmbiguousOid { prefix, candidates }` | 缩写 OID 解析失败 |+| 并发 | `ConcurrentCommit` | CAS 失败(由 ref\_store conflict 上抛) |+| 资源限制 | `BlobTooLarge { path, size, max }`、`TooManyFiles { count, max }`、`InvalidAccountId(String)` | 已定义但**当前无运行时检查**,详见 §12.3 |+| 其他 | `FeatureDisabled`、`CorruptedObject(...)`、`Other(String)` | binding 关闭、对象腐烂、兜底 |++## 13.2 Python 异常映射++| Rust Error | Python Exception | 语义 |+| -------------------------------------------------------------------- | --------------------------- | ----------- |+| `FeatureDisabled` | `AGFSNotSupportedError` | git 模块未启用 |+| `ConcurrentCommit` | `GitConcurrentCommitError` | 需要上层重试或人工介入 |+| `PathNotFound` / `OidPrefixNotFound` / 后端 NotFound | `AGFSNotFoundError` | 404 语义 |+| `PathIsDirectory` / `BlobTooLarge` / `TooManyFiles` / `AmbiguousOid` | `AGFSInvalidOperationError` | 入参或资源错误 |+| `InvalidAccountId` / `InvalidProjectDir` | `AGFSInvalidPathError` | 路径/账号 ID 非法 |+| `CorruptedObject` / `Other` / `Vfs` | `AGFSInternalError` | 底层异常 |++***++# 14. 可观测性++> **当前状态:** §14.1/§14.2 中描述的 tracing span / metrics **MVP 尚未接入**;§14.3 健康检查仅暴露 `git_enabled` / `git_backend` 两个字段。下面保留为目标态,未带状态标注的均为待实现项。++## 14.1 Tracing/日志关键字段(目标态)++- **span 名**: `git.commit`, `git.restore`, `git.show`+- **tag**: `account_id`, `branch`, `parent_oid`, `commit_oid`, `backend`+- **event**: `git.blob.put`(`oid`, `size`), `git.tree.write`, `git.ref.cas`(`expected`, `new`, `result`), `git.cas.conflict`++## 14.2 Metrics(目标态)++| 指标 | 类型 | 维度 |+| ---------------------------------- | --------- | ---------------------------- |+| `git_commit_total` | counter | account\_id, branch, result |+| `git_commit_duration_seconds` | histogram | backend |+| `git_commit_files` | histogram | — |+| `git_commit_bytes` | histogram | backend |+| `git_cas_conflict_total` | counter | account\_id, branch |+| `git_object_store_latency_seconds` | histogram | op (put/get/exists), backend |+| `git_ref_store_latency_seconds` | histogram | op (read/cas), backend |++## 14.3 健康检查++- **当前实现**: `RAGFSBindingClient.health()` 在原有字段上追加 `git_enabled: bool` 和 `git_backend: Option<String>`(关闭时为 None)。+- **目标态(未实现)**: 增加 `git` 子结构,返回 `{"backend", "writable", "last_commit_age_sec"}`;每分钟后台心跳对 `refs/heads/main` 做一次 read,失败则标记 degraded。++***++# 15. 测试策略++## 15.1 测试层次++| 层级 | 范围 |+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |+| **单元测试 (Rust)** | ObjectStore 各操作的幂等性;RefStore CAS 在并发下的正确性(MVP 用普通并发测,未引入 loom);tree\_builder 的 upsert/remove/write;错误映射 |+| **集成测试 (Rust)** | LocalObjectStore 跑全套场景(MVP 暂未引入 MemObjectStore);commit → show 路径 → bytes 一致;commit → restore → 文件一致;并发 commit 的 CAS 冲突处理 |+| **端到端 (Python)** | VikingFS.commit → restore 全流程;跨 scope 原子快照;派生文件被正确纳入 commit 并随 restore 回滚;向量索引在 restore 后被精确重建;多账号并发隔离 |++## 15.2 关键测试用例清单++1. **幂等性**: 同一 commit\_req 调用两次,第二次应快速返回(blob exists 跳过 + ref 未变 → no-op 或 same oid)+2. **跨 scope 原子性**: 一次 commit 同时改 `resources/a.md` 和 `agent/skills/b.py`,restore 父 commit 后两者都应回滚+3. **派生文件纳入**: 创建 `resources/x.md` 与 `resources/x.md.abstract.md`,commit 后 `show` 两者均可见;restore 父 commit 后两者都应回滚;向量索引文件不被 commit+4. **CAS 冲突**: 两个并发 commit,后到的必须看到 `ConcurrentCommit` 错误而非默默覆盖+5. **dry\_run 不写**: restore dry\_run 后再 ls,VFS 状态不变+6. **账号隔离**: A 账号的 commit\_oid 在 B 账号下 show 必须返回 not found+7. **后端等价性**: LocalObjectStore 与 S3ObjectStore (LocalStack/MinIO) 跑同一组用例输出一致+8. **大文件**: 单 blob 80MB 可正确 commit / show / restore+9. **双重加密**: restore 写回后 VFS read 内容与原始明文一致++***++# 16. 实施计划 (MVP)++| 阶段 | 工作内容 | 交付物 | 预估 |+| ----- | --------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---- |+| D1-D2 | 新建 `crates/ragfs/src/git/`,定义 trait + LocalObjectStore/LocalRefStore + S3ObjectStore/S3RefStore (含 If-Match CAS) + 单测 | 裸 Git 存储跑通 put/get/CAS | 2d |+| D3 | 接入 `gix_object::tree::Editor`,实现 `GitService::commit` | commit 流程单测绿 | 1d |+| D4 | 实现 `GitService::show` (纯读路径,易验证) | commit + show 闭环 | 1d |+| D5 | 实现 `GitService::restore`,dry\_run 优先,验证幂等 | commit + restore 闭环 | 1d |+| D6 | PyO3 binding: `RAGFSBindingClient` 三个新方法 + 错误映射 | Python 端可调 | 1d |+| D7 | `VikingFS.commit/restore/show/log` + URI ↔ tree path 转换 | Python 端到端 | 1d |+| D9 | tracing/metrics 接入 + health check | 可观测性完备 | 0.5d |+| D10 | 文档 + 灰度发布 | 上线 Phase 1 | 0.5d |++> 💡 **总工期**: \~10 人日 (MVP, 单人); 双后端等价测试与 S3 CAS 兼容性验证可能引入额外 2-3 天。++***++# 17. 当前实现进度与未实现项++下面汇总文档中已写出但当前**尚未实现**的部分,供后续阶段补齐:++### Rust 侧++- **commit / restore 内部 CAS 重试循环** —— 文档 §11.3 旧版描述。当前 `commit()` 明确不做 retry,`ConcurrentCommit` 直接上抛。+- *git.tuning.* 配置项接入\* —— 文档 §10.1。`upload_concurrency` / `restore_concurrency` / `ref_cas_max_retry` / `ref_cas_backoff_ms` 已在 `GitTuningConfig` 中定义并解析,但代码尚未读取(restore 回写并发度硬编码 32,commit blob 上传为串行)。+- **S3 RedisLock CAS 模式** —— 文档 §7.2。`CasMode::RedisLock` 仅作为枚举占位,实际调用返回 "not yet implemented" 错误。+- **资源限制实际生效** —— 文档 §12.3。`BlobTooLarge` / `TooManyFiles` / `[git.quota]` 配置块均未实现(仅错误 variant 已定义)。同账号 restore 写竞态防护已通过 `VikingFS.restore` 的 `LockContext` 树锁实现(见 §12.3)。+- **账号 ID 校验** —— 文档 §12.1。`validate_account_id` 未实现,`GitError::InvalidAccountId` 仅占位。+- **本地 ref 跨进程锁** —— 文档 §7.1。`LocalRefStore` 仅有进程内 `DashMap<Mutex>`,未叠加 `flock`。+- **观测性 (tracing / metrics)** —— 文档 §14.1 / §14.2。span / event / 各类 counter / histogram 均未接入。+- **健康检查增强** —— 文档 §14.3。当前仅 `git_enabled` / `git_backend`,未接入 `writable` / `last_commit_age_sec` / 心跳。+- **GC / pack file / branch & tag 管理 / diff API** —— 文档 §19。属后续 Phase。+- **loom 并发模型测试 + proptest fuzz** —— 文档 §5.2。MVP 未引入。+- 在版本管理中忽略某些特定文件 uri,类似 .gitignore 功能的实现。++### Python 侧++- **VikingFS.commit / restore / show / log 已实现**(`openviking/storage/viking_fs.py`),`_uri_to_tree_path` / `_tree_path_to_uri` / `_classify_restore_path` / `_schedule_vector_rebuild` / `_run_vector_rebuild` 均已实现,精确按 marker / source-file / `.relations.json` 调度 `ReindexExecutor`。+- **VikingFS.\_trigger\_vector\_rebuild(account, paths)(早期设计)** 已被更精确的 `_schedule_vector_rebuild(written, deleted)` 替代,**不会**再实现旧 API。++***++# 18. 风险与缓解++| 风险 | 影响 | 缓解 |+| -------------------------------------- | -- | ----------------------------------------------------------------------------------- |+| S3/TOS CAS 兼容性差异 | 高 | POC 阶段验证目标后端的 If-Match 条件写支持;不支持时该后端不可用于 git ref 存储 |+| 大账号 commit 时 enumerate 慢 | 中 | `paths` 参数限定 scope;后续引入增量 diff(基于 mtime + parent tree) |+| 双重加密导致 restore 后内容损坏 | 高 | restore 路径绕过 `viking_fs.write` 加密,直接走 `MountableFS`;集成测试覆盖 |+| L0/L1 派生文件纳入版本历史,模型异步重建导致 commit 间差异增加 | 中 | 用户主动控制 commit 时机,不自动触发;L0/L1 文件通常较小(< 10KB),存储成本可控;如需降频可配置 commit 时忽略 mtime-only 变更 |+| 同一账号多 Agent 高并发 commit | 中 | CAS 冲突自动重试 3 次;长期可引入"基于队列的串行化提交器" |+| Git 数据无 GC,长期膨胀 | 中 | 首版不做 GC,运维侧定期 dump + 压缩;后续接入 reachability-based GC |+| loose object 数量爆炸,本地 inode 紧张 | 低 | Phase 4 引入 pack file;Git fanout 已经缓解一半 |++***++# 19. 后续演进方向++1. **Pack file 支持**: 引入 `gix-pack`,对历史 commit 做 delta 压缩,降低存储成本 80%++2. **Auto-commit hook**: 在 `content_write.ContentWriteCoordinator` 末尾追加可选 hook,实现"每次写自动 commit"模式(Phase 2 重新评估)+3. **Branch / Tag 管理**: 暴露 `branch_create / branch_delete / tag` API+4. **Diff API**: `diff(ref_a, ref_b)` 返回结构化差异,供 UI 渲染+5. **跨账号镜像**: 支持账号间的 commit 分享(类似 GitHub fork)+6. **向量索引版本化(可选)**: 若后续需要向量索引的快照回滚能力,可引入轻量 manifest 记录 index 版本与对应 commit\_oid 的映射,避免全量存储向量数据+7. **外部 Git 工具兼容**: 输出标准 Git 仓库格式,允许通过 `git clone file://...` 检视++***++# 20. 附录++## 20.1 术语表++| 术语 | 含义 |+| ------------ | ------------------------------------------------------------------------------------------------ |+| VFS | Virtual File System,本文特指 OpenViking 的 `MountableFS` + plugin 体系 |+| Loose Object | Git 的基础存储单元,zlib 压缩,按 SHA 寻址的单文件 |+| CAS | Compare-And-Swap,本文特指 ref 更新时"仅当当前值 = 期望值才写入" |+| Root Tree | commit 对象指向的最顶层 tree 对象,代表整个仓库快照 |+| Tree Editor | `gix_object::tree::Editor`,gitoxide 提供的内存中 tree 构建器,支持 upsert/remove/write |+| 派生文件 | `.abstract.md` / `.overview.md` / `.relations.json`,由 OpenViking 模型异步生成的 L0/L1 摘要文件,已纳入 Git 版本管理 |++## 20.2 参考资料++- [GitoxideLabs/gitoxide](https://github.com/GitoxideLabs/gitoxide)+- [volcengine/OpenViking](https://github.com/volcengine/OpenViking)+- [OpenViking 存储架构文档](https://github.com/volcengine/OpenViking/blob/main/docs/zh/concepts/05-storage.md)+- [Git Pack Format (后续 Phase 参考)](https://git-scm.com/docs/gitformat-pack)++> 💡 **文档完成**。如需对某一章节细化(如某后端实现细节、某测试用例代码、迁移脚本),请告知具体目标。+diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.mdindex 26ff18b1f..977d72a4c 100644--- a/docs/en/api/01-overview.md+++ b/docs/en/api/01-overview.md@@ -435,6 +435,15 @@ Below are all HTTP API endpoints provided by OpenViking, grouped by functional m| DELETE | `/api/v1/fs` | Delete resource || POST | `/api/v1/fs/mv` | Move/rename resource |+### Snapshots (Multi-Version Management)++| Method | Path | Description |+|--------|------|-------------|+| POST | `/api/v1/snapshot/commit` | Save the current workspace state as a new snapshot |+| GET | `/api/v1/snapshot/log` | Walk commit history newest-first |+| GET | `/api/v1/snapshot/show` | View commit metadata, or read a file from a commit |+| POST | `/api/v1/snapshot/restore` | Restore a directory or the whole account tree to a past snapshot (forward commit) |+### Content| Method | Path | Description |@@ -569,6 +578,7 @@ Subsequent API documentation is organized by functional module as follows:| [Resources](02-resources.md) - Resource management API | Adding, importing, exporting resources and skills || [Retrieval](06-retrieval.md) - Search API | Search, relations, context acquisition || [File System](03-filesystem.md) - File system operations | Directory operations, content reading and writing |+| [Snapshots](11-snapshot.md) - Multi-version management | Snapshot commit, history walk, version restore || [Sessions](05-sessions.md) - Session management | Session creation, message management, memory extraction || [Skills](04-skills.md) - Skill management API | Skill management || [System](07-system.md) - System and monitoring API | System status, monitoring, debug API |diff --git a/docs/en/api/11-snapshot.md b/docs/en/api/11-snapshot.mdnew file mode 100644index 000000000..bd8147b29--- /dev/null+++ b/docs/en/api/11-snapshot.md@@ -0,0 +1,427 @@+# Snapshots (Multi-Version Management)++On top of VikingFS, OpenViking provides Git-based multi-version management, called **Snapshots**. It saves an account's entire resource tree as a series of immutable commits, letting you walk history, compare versions, and restore the workspace to any past state.++Snapshots are powered by [gitoxide](https://github.com/Byron/gitoxide) embedded in the Rust RAGFS layer, maintaining one logical Git repository per `account_id`. This is fully transparent to callers — you never touch a `.ovgit` directory, the object store, or ref internals.++The four core commands:++| Command | Purpose |+|---------|---------|+| `commit` | Save the current workspace state as a new snapshot |+| `log` | Walk commit history starting from the newest |+| `show` | View a commit's metadata, or read a file's content from that commit |+| `restore` | Restore a directory (or the whole account tree) to a past snapshot |++## Core Concepts++- **Commit**: A snapshot is a commit, uniquely identified by a 40-hex SHA-1 `commit_oid`. Most commands also accept an abbreviated OID prefix or a branch name (e.g. `main`).+- **Branch**: The default branch is `main`. Unless you pass one explicitly, every command operates on `main`.+- **Forward-commit restore**: `restore` does **not** rewind or rewrite history. It reads the content at `source_commit`, writes the diff back into the workspace, and creates a **new commit on top of the current HEAD**. The new commit's parent is therefore the HEAD that existed before the restore — **not** `source_commit`. HEAD always advances monotonically and history is never lost.+- **Scope**: `commit` can be limited to specific URIs via `paths`; `restore` can be limited to a subtree via `project_dir`, leaving files outside it untouched.++## Implementation++- HTTP routes: [snapshot.py](file:///cloudide/workspace/OpenViking/openviking/server/routers/snapshot.py), prefix `/api/v1/snapshot`.+- SDK namespace: [snapshot_namespace.py](file:///cloudide/workspace/OpenViking/openviking/snapshot_namespace.py), exposed as `client.snapshot.*`.+- Underlying semantics: `commit` / `restore` / `show` / `log` in [viking_fs.py](file:///cloudide/workspace/OpenViking/openviking/storage/viking_fs.py).+- CLI: the `SnapshotCmd` in [main.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/main.rs), subcommands in [snapshot.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/commands/snapshot.rs).++## API Reference++### commit()++Save the current workspace state as a new snapshot.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| message | str | Yes | - | Commit message |+| paths | List[str] | No | null | `viking://` URIs to scope the snapshot to; entries may be files or directories. Directories are expanded recursively with the snapshot pruning rules applied. `null` snapshots the whole account tree. An empty list `[]` is forwarded as an explicit empty path set (no-op). A path that exists in neither the VFS nor the previous snapshot logs a warning and is treated as a no-op deletion |+| branch | str | No | `main` | Branch to advance |+| author_name | str | No | null | Override the default author name (default `viking-bot`) |+| author_email | str | No | null | Override the default author email |++**Python SDK (Embedded / HTTP)**++```python+result = client.snapshot.commit(+ message="v1 initial import",+ paths=["viking://resources/my_md.md"],+)+print(result["commit_oid"])+```++**HTTP API**++```+POST /api/v1/snapshot/commit+```++```bash+curl -X POST "http://localhost:1933/api/v1/snapshot/commit" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "message": "v1 initial import",+ "paths": ["viking://resources/my_md.md"]+ }'+```++**CLI**++```bash+ov snapshot commit -m "v1 initial import" --paths viking://resources/my_md.md -o json+```++**Response**++When a new snapshot is created:++```json+{+ "status": "ok",+ "result": {+ "result": "created",+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "changed": 3+ }+}+```++When the workspace is unchanged relative to the last commit, the result is `noop` and `commit_oid` is the current HEAD:++```json+{+ "status": "ok",+ "result": {+ "result": "noop",+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ }+}+```++---++### log()++Starting from a branch's HEAD, walk history along the first parent (`parents[0]`) and return commits newest-first.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| branch | str | No | `main` | Branch to walk |+| limit | int | No | 20 | Max commits to return. The HTTP endpoint clamps this to 1–500 |++**Python SDK (Embedded / HTTP)**++```python+history = client.snapshot.log(limit=10)+for commit in history:+ print(commit["oid"], commit["message"])+```++**HTTP API**++```+GET /api/v1/snapshot/log?branch={branch}&limit={limit}+```++```bash+curl -X GET "http://localhost:1933/api/v1/snapshot/log?branch=main&limit=10" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot log --limit 10 -o json+```++**Response**++`result` is a list of commit metadata, each element having the same shape as the metadata returned by [show()](#show):++```json+{+ "status": "ok",+ "result": [+ {+ "oid": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "tree": "11223344556677889900aabbccddeeff00112233",+ "parents": ["3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"],+ "author": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750300000,+ "tz_offset_seconds": 28800+ },+ "committer": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750300000,+ "tz_offset_seconds": 28800+ },+ "message": "v2 modify delete add"+ }+ ]+}+```++> When the branch has no commits yet, the HTTP endpoint returns `404 NOT_FOUND`.++---++### show()++View a commit's metadata; if `path` is given, return that file's content from the commit instead.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| target_ref | str | Yes | - | Commit OID (abbreviated prefix allowed), branch name, or tag |+| path | str | No | null | `viking://` URI of a single file; omit to return commit metadata |++**Python SDK (Embedded / HTTP)**++```python+# View commit metadata+meta = client.snapshot.show("3f2a1b9c")+print(meta["message"], meta["parents"])++# Read a file's content from the commit+blob = client.snapshot.show("3f2a1b9c", path="viking://resources/my_project/guide.md")+```++> Note: when reading a file (`path` given), the **Embedded (local) client** returns raw `bytes`, while the **HTTP client** returns a `{"oid": str, "size": int, "bytes": bytes}` dict.++**HTTP API**++```+GET /api/v1/snapshot/show?target_ref={ref}[&path={uri}]+```++```bash+# Commit metadata (returns JSON)+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=3f2a1b9c" \+ -H "X-API-Key: your-key"++# File content (returns a binary stream)+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=3f2a1b9c&path=viking://resources/my_project/guide.md" \+ -H "X-API-Key: your-key"+```++Without `path`, the response is commit metadata JSON. With `path`, the response is a raw byte stream (`Content-Type: application/octet-stream`) plus two headers:++- `X-Snapshot-Oid`: the blob object's OID+- `X-Snapshot-Size`: the blob size in bytes++**CLI**++```bash+# Commit metadata+ov snapshot show 3f2a1b9c -o json++# Read file content (defaults to stdout; use --out-file to write to a local file)+ov snapshot show 3f2a1b9c --path viking://resources/my_project/guide.md --out-file ./guide.md+```++**Response (commit metadata)**++```json+{+ "status": "ok",+ "result": {+ "oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "tree": "00112233445566778899aabbccddeeff00112233",+ "parents": [],+ "author": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750299000,+ "tz_offset_seconds": 28800+ },+ "committer": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750299000,+ "tz_offset_seconds": 28800+ },+ "message": "v1 initial import"+ }+}+```++---++### restore()++Restore a directory (or the whole account tree) to its state at `source_commit`.++This is a **forward-commit restore**: it computes the diff between `source_commit` and the current HEAD, writes it back into the workspace, and creates a **new commit on top of the current HEAD**. The new commit's parent is the pre-restore HEAD (not `source_commit`), so history is never rewritten. Files outside `project_dir` are left untouched.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| source_commit | str | Yes | - | What to restore from: commit OID (abbreviated prefix allowed), branch name, or tag |+| project_dir | str | No | null | `viking://` URI of the subtree to restore; omit to restore the whole account tree |+| branch | str | No | `main` | Branch to advance |+| dry_run | bool | No | false | Compute and return the diff only; write nothing |+| message | str | No | null | Message for the new commit; auto-generated when omitted |+| author_name | str | No | null | Override the default author name |+| author_email | str | No | null | Override the default author email |++**Python SDK (Embedded / HTTP)**++```python+result = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ message="restore to v1",+)+print(result["result"], result["new_commit_oid"])++# Preview which files would change first+plan = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ dry_run=True,+)+print(plan["diff"])+```++**HTTP API**++```+POST /api/v1/snapshot/restore+```++```bash+curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "project_dir": "viking://resources/my_project",+ "source_commit": "3f2a1b9c",+ "message": "restore to v1"+ }'+```++**CLI**++```bash+# Positional args are <source_commit> then <project_dir>+ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json++# Dry run+ov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json+```++**Response (applied)**++On a successful write that produces a new commit, `result` is `applied`. Note `parent_commit` equals the old (pre-restore) HEAD, confirming the forward-commit semantics:++```json+{+ "status": "ok",+ "result": {+ "result": "applied",+ "new_commit_oid": "c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f50",+ "source_commit": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "parent_commit": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "written": 1,+ "deleted": 1,+ "unchanged": 1,+ "written_paths": ["resources/my_project/guide.md"],+ "deleted_paths": ["resources/my_project/changelog.md"],+ "task_id": "snapshot_restore_reindex-..."+ }+}+```++When the restore has vector side effects (files written/deleted), the response carries a `task_id` you can poll via `GET /api/v1/tasks/{task_id}` to track the background vector rebuild.++**Response (noop)**++When the source is byte-identical to the current state, the result is `noop` and no new commit is created:++```json+{+ "status": "ok",+ "result": {+ "result": "noop",+ "head": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "source": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ }+}+```++**Response (dry_run)**++With `dry_run=true`, only the planned diff is returned and nothing is written. Diff paths are relative to `project_dir`:++```json+{+ "status": "ok",+ "result": {+ "result": "dry_run",+ "head": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "source": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "diff": {+ "to_write": [{"path": "guide.md", "oid": "..."}],+ "to_delete": ["changelog.md"],+ "unchanged": ["notes/todo.md"]+ }+ }+}+```++## A Typical Flow++A complete "commit → modify → restore" flow (Python SDK):++```python+import openviking as ov++client = ov.OpenViking()+client.initialize()++root = "viking://resources/my_project"++# 1. Write initial content and commit v1+client.write(f"{root}/guide.md", "# Guide\n\nv1 content\n", mode="create", wait=True)+v1 = client.snapshot.commit(message="v1 initial import")++# 2. Modify and commit v2+client.write(f"{root}/guide.md", "# Guide\n\nv2 content\n", mode="replace", wait=True)+v2 = client.snapshot.commit(message="v2 update")++# 3. Walk history+for c in client.snapshot.log(limit=10):+ print(c["oid"][:8], c["message"])++# 4. Restore the workspace to v1 (creates a new commit on top of v2)+client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], message="restore to v1")++client.close()+```++For more end-to-end examples, see the [examples/snapshot/](file:///cloudide/workspace/OpenViking/examples/snapshot) directory in the repository, covering the SDK, HTTP, and CLI surfaces.++## Error Handling++| Scenario | HTTP Status | Error Code |+|----------|-------------|------------|+| Branch/commit not found, or `show`'s `path` does not exist in that commit | 404 | `NOT_FOUND` |+| Branch concurrently advanced during restore (CAS conflict) | 409 | `CONFLICT` |+| Request body contains an unknown field (request model is `extra="forbid"`) | 400 | `INVALID_ARGUMENT` |++## Related Documentation++- [File System](03-filesystem.md): snapshots build on filesystem resources+- [System](07-system.md): track the background vector rebuild triggered by restore via `GET /api/v1/tasks/{task_id}`+- [API Overview](01-overview.md): full endpoint referencediff --git a/docs/en/guides/13-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.mdsimilarity index 100%rename from docs/en/guides/13-ragfs-cache.mdrename to docs/en/guides/14-ragfs-cache.mddiff --git a/docs/en/guides/15-snapshot.md b/docs/en/guides/15-snapshot.mdnew file mode 100644index 000000000..5295f41dc--- /dev/null+++ b/docs/en/guides/15-snapshot.md@@ -0,0 +1,228 @@+# Snapshots (Multi-Version Management) Guide++This guide explains how to enable and use OpenViking's multi-version management (snapshots). On top of VikingFS, it provides Git-based `commit`/`log`/`show`/`restore` primitives, letting you save an account's resource tree as a series of immutable snapshots, walk history, compare versions, and restore the workspace to any past state.++Multi-version management is powered by [gitoxide](https://github.com/Byron/gitoxide) embedded in the Rust RAGFS layer, maintaining one logical Git repository per `account_id`. It is fully transparent to callers — you never run any `git` command yourself.++> For the full API reference of each command's parameters and responses, see [Snapshots API](../api/11-snapshot.md).++## Prerequisites++- You already have a working `ov.conf`.+- Resource read/write is verified to work (snapshots build on filesystem resources).+- If you choose the S3 backend for Git objects, prepare the bucket, region, endpoint, and access credentials first.++## Enabling Multi-Version Management++Multi-version management is **enabled** by default (`git.enabled` defaults to `true`). The Git object backend can be `local` (local filesystem) or `s3` (S3-compatible object storage); when `git.backend` is not set explicitly, it **inherits `storage.agfs.backend`** (a `memory` storage backend maps to `local`). To turn multi-version management off, set `git.enabled` to `false`.++### Local Backend (recommended for single-node deployments)++```json+{+ "storage": {+ "workspace": "./data"+ },+ "git": {+ "enabled": true,+ "backend": "local",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "local": {+ "base_dir": ""+ }+ }+}+```++Configuration reference:++| Field | Default | Description |+|-------|---------|-------------|+| `git.enabled` | `true` | Whether multi-version management is on. Set to `false` to disable snapshot commands |+| `git.backend` | inherits `storage.agfs.backend` | Git object backend: `local` or `s3`. When not set explicitly, inherits `storage.agfs.backend` (`memory` maps to `local`) |+| `git.default_branch` | `main` | Default branch name when none is specified |+| `git.author_name` | `viking-bot` | Default author name when callers omit `author_name` |+| `git.author_email` | `[email protected]` | Default author email |+| `git.local.base_dir` | `""` | Directory holding Git objects/refs. **When empty, defaults to `{storage.workspace}/.ovgit`** |++> Usually leave `git.local.base_dir` empty so snapshot data lands in `.ovgit` under the workspace, making it easy to back up and migrate alongside resource data.++### S3 Backend (recommended for distributed / cloud deployments)++Stores Git objects and refs in S3-compatible object storage (e.g. Volcengine TOS, MinIO, AWS S3). When `backend` is `s3`, the `git.s3` section is **required**, and `bucket` and `region` must not be empty.++> Tip: the `git.s3` fields `bucket`, `region`, `endpoint`, `access_key`, and `secret_key` **inherit the matching `storage.agfs.s3`** values when not set explicitly. So when `storage.agfs` is already configured as an s3 backend, you usually don't need to repeat `git.s3` — as long as `git.backend` is not set explicitly, multi-version management reuses the bucket and credentials from `storage.agfs`.++```json+{+ "storage": {+ "workspace": "./data"+ },+ "git": {+ "enabled": true,+ "backend": "s3",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "s3": {+ "bucket": "your-tos-bucket",+ "region": "cn-beijing",+ "endpoint": "https://tos-s3-cn-beijing.volces.com",+ "access_key": "<your-volcengine-ak>",+ "secret_key": "<your-volcengine-sk>",+ "prefix": ".ovgit",+ "use_path_style": false,+ "cas_mode": "native"+ }+ }+}+```++Configuration reference:++| Field | Default | Description |+|-------|---------|-------------|+| `git.s3.bucket` | inherits `storage.agfs.s3.bucket` | Bucket holding Git objects/refs. Required (may be inherited from `storage.agfs.s3`) |+| `git.s3.region` | inherits `storage.agfs.s3.region`, else `us-east-1` | Region the bucket is in. Required |+| `git.s3.prefix` | `.ovgit` | Key prefix; all data is stored under `{prefix}/{account}/...` |+| `git.s3.endpoint` | inherits `storage.agfs.s3.endpoint`, else `""` | Custom S3 endpoint (MinIO/TOS, etc.); leave empty for standard AWS S3 |+| `git.s3.access_key` / `git.s3.secret_key` | inherit the matching `storage.agfs.s3` fields, else `null` | Credentials read directly; empty falls back to the SDK default credentials chain |+| `git.s3.use_path_style` | `true` | `true` uses path-style addressing (MinIO, etc.); `false` uses virtual-host style (TOS, etc.) |+| `git.s3.cas_mode` | `native` | Ref CAS mode. `native` uses S3 conditional writes (If-Match) |++After editing the config, restart the OpenViking service (or re-initialize the SDK client) for it to take effect.++> The repository ships ready-to-use examples: [ov.conf.git-local.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-local.example) and [ov.conf.git-s3-tos.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-s3-tos.example).++## Directory Layout Change: the `.ovgit` Directory++When the `local` backend is enabled and `base_dir` is left empty, OpenViking adds a **`.ovgit`** directory under the workspace to hold Git objects and refs:++```text+data/ # storage.workspace+├── viking/ # user-visible resource tree (viking:// maps here)+│ └── ...+└── .ovgit/ # multi-version management data (new)+ └── {account_id}/ # one logical Git repository per account+ ├── objects/ # Git objects (commit/tree/blob), standard fanout aa/bb...+ ├── refs/+ │ └── heads/+ │ └── main # branch ref, content is a 40-hex OID+ └── HEAD # current branch pointer, content "ref: refs/heads/main"+```++Key points:++- `.ovgit` is an internal data directory. It is **not** exposed through `viking://` — users cannot see or modify it through the filesystem APIs (`ls`/`read`, etc.).+- Its layout matches a standard Git object store (content-addressed `objects/`, loose `refs/`), but it is managed automatically by OpenViking. You should **not** run `git` commands against it.+- When backing up or migrating the workspace, copy `.ovgit` along with it to preserve the full version history.+- With the `s3` backend, no local `.ovgit` directory is created; data lives under the bucket's `{prefix}/{account}/...` keys instead.++## Usage++Once enabled, all three surfaces expose snapshot commands. The examples below show a minimal "commit → modify → restore" flow.++### Python SDK++Snapshot methods live under the `client.snapshot.*` namespace.++```python+import openviking as ov++client = ov.OpenViking()+client.initialize()++root = "viking://resources/my_project"++# 1. Write initial content and commit v1+client.write(f"{root}/guide.md", "# Guide\n\nv1 content\n", mode="create", wait=True)+v1 = client.snapshot.commit(message="v1 initial import")+print("v1:", v1["commit_oid"])++# 2. Modify and commit v2+client.write(f"{root}/guide.md", "# Guide\n\nv2 content\n", mode="replace", wait=True)+v2 = client.snapshot.commit(message="v2 update")++# 3. Walk history+for c in client.snapshot.log(limit=10):+ print(c["oid"][:8], c["message"])++# 4. Inspect a commit's metadata+print(client.snapshot.show(v1["commit_oid"])["message"])++# 5. Restore the workspace to v1 (creates a new "forward" commit on top of v2)+client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], message="restore to v1")++client.close()+```++### CLI++The CLI subcommands live under `ov snapshot`:++```bash+# Commit the current workspace state+ov snapshot commit -m "v1 initial import" -o json++# Walk history (newest first)+ov snapshot log --limit 10 -o json++# View commit metadata+ov snapshot show <commit_oid> -o json++# Read a file's content from a commit (defaults to stdout; use --out-file to write a local file)+ov snapshot show <commit_oid> --path viking://resources/my_project/guide.md --out-file ./guide.md++# Restore a directory to a past snapshot (positional args are <source_commit> then <project_dir>)+ov snapshot restore <commit_oid> viking://resources/my_project -m "restore to v1" -o json++# Preview which files would change first+ov snapshot restore <commit_oid> viking://resources/my_project --dry-run -o json+```++### HTTP API++```bash+# Commit+curl -X POST "http://localhost:1933/api/v1/snapshot/commit" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"message": "v1 initial import"}'++# Walk history+curl -X GET "http://localhost:1933/api/v1/snapshot/log?branch=main&limit=10" \+ -H "X-API-Key: your-key"++# View commit metadata+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=<commit_oid>" \+ -H "X-API-Key: your-key"++# Restore+curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"project_dir": "viking://resources/my_project", "source_commit": "<commit_oid>", "message": "restore to v1"}'+```++## Key Semantics: Forward-Commit Restore++`restore` uses **forward-commit** semantics: it reads the content at `source_commit`, writes the diff back into the workspace, and creates a **new commit on top of the current HEAD**. Therefore:++- The new commit's parent is the HEAD that existed before the restore — **not** `source_commit`.+- HEAD always advances monotonically, and **history is never rewritten or lost** — going back to an older version is itself a new commit.+- `restore` only affects files within `project_dir` (the whole account tree when omitted); files outside that scope are left untouched.++## Notes++- After editing the `git` config, restart the service / re-initialize the client for it to take effect.+- With the `s3` backend, `git.s3.bucket` and `git.s3.region` are required; missing them causes initialization to fail.+- If a restore has vector side effects (files written/deleted), the response carries a `task_id` you can poll via `GET /api/v1/tasks/{task_id}` to track the background vector rebuild (see the [Observability guide](05-observability.md) and [API Overview](../api/01-overview.md)).+- Do not operate on the `.ovgit` directory with an external `git` tool; it is maintained by OpenViking.++## Related Documentation++- [Snapshots API](../api/11-snapshot.md): full reference of command parameters and responses+- [Configuration](01-configuration.md): full `ov.conf` reference+- [Multi-Write Storage Guide](13-multi-write-storage.md): multi-backend replication of resource datadiff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.mdindex b77a05746..d57ad5f89 100644--- a/docs/zh/api/01-overview.md+++ b/docs/zh/api/01-overview.md@@ -431,6 +431,15 @@ JSON 输出 - 错误:| DELETE | `/api/v1/fs` | 删除资源 || POST | `/api/v1/fs/mv` | 移动/重命名资源 |+### 快照端点(多版本管理)++| 方法 | 路径 | 说明 |+|------|------|------|+| POST | `/api/v1/snapshot/commit` | 把当前工作区状态保存成新快照 |+| GET | `/api/v1/snapshot/log` | 从最新提交开始回溯历史 |+| GET | `/api/v1/snapshot/show` | 查看提交元数据,或读取提交中某个文件 |+| POST | `/api/v1/snapshot/restore` | 恢复目录或整棵账号树到某个历史快照(正向提交) |+### 内容端点| 方法 | 路径 | 说明 |@@ -564,6 +573,7 @@ VikingBot API 需要服务器启动时指定 `--with-bot` 选项:|------|------|| [资源管理](02-resources.md) | 资源和技能的添加、导入、导出 || [文件系统](03-filesystem.md) | 目录操作、内容读写 |+| [多版本管理](11-snapshot.md) | 快照提交、历史回溯、版本恢复 || [技能](04-skills.md) | 技能管理 API || [会话管理](05-sessions.md) | 会话创建、消息管理、记忆提取 || [检索](06-retrieval.md) | 搜索、关联、上下文获取 |diff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.mdnew file mode 100644index 000000000..da1345f0c--- /dev/null+++ b/docs/zh/api/11-snapshot.md@@ -0,0 +1,427 @@+# 多版本管理(快照)++OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力,称为**快照(Snapshot)**。它把某个账号(account)下的整棵资源树保存成一系列不可变的提交(commit),让你能够回溯历史、对比版本,并把工作区恢复到任意一个历史状态。++快照能力底层由内嵌在 Rust RAGFS 层的 [gitoxide](https://github.com/Byron/gitoxide) 驱动,按 `account_id` 维护一个逻辑 Git 仓库(每个账号一个仓库),对调用方完全透明——你无需关心 `.ovgit` 目录、对象库或引用细节。++四个核心命令:++| 命令 | 作用 |+|------|------|+| `commit` | 把当前工作区状态保存成一个新快照 |+| `log` | 从最新提交开始回溯历史 |+| `show` | 查看某个提交的元数据,或读取该提交中某个文件的内容 |+| `restore` | 把目录(或整棵账号树)恢复到某个历史快照的状态 |++## 核心概念++- **提交(commit)**:一个快照对应一个提交,由 40 位十六进制的 SHA-1 `commit_oid` 唯一标识。多数命令也接受 OID 的缩写前缀,或分支名(如 `main`)。+- **分支(branch)**:默认分支为 `main`。除非显式传入,所有命令都作用在 `main` 上。+- **正向恢复(forward-commit restore)**:`restore` **不会**回退或改写历史。它会读取 `source_commit` 的内容,把差异写回工作区,并在当前 HEAD 之上**生成一个新的提交**。因此新提交的父提交是恢复操作发生前的 HEAD,而**不是** `source_commit`。HEAD 始终单调向前推进,历史永远不会丢失。+- **作用范围**:`commit` 可以通过 `paths` 限定只快照部分 URI;`restore` 可以通过 `project_dir` 限定只恢复某个子目录,目录之外的文件保持不变。++## API 实现介绍++- HTTP 路由:[snapshot.py](file:///cloudide/workspace/OpenViking/openviking/server/routers/snapshot.py),前缀 `/api/v1/snapshot`。+- 命名空间(SDK):[snapshot_namespace.py](file:///cloudide/workspace/OpenViking/openviking/snapshot_namespace.py),暴露为 `client.snapshot.*`。+- 底层语义实现:[viking_fs.py](file:///cloudide/workspace/OpenViking/openviking/storage/viking_fs.py) 的 `commit` / `restore` / `show` / `log`。+- CLI 命令:[main.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/main.rs) 的 `SnapshotCmd`,子命令 [snapshot.rs](file:///cloudide/workspace/OpenViking/crates/ov_cli/src/commands/snapshot.rs)。++## API 参考++### commit()++把当前工作区状态保存成一个新的快照。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| message | str | 是 | - | 提交说明 |+| paths | List[str] | 否 | null | 限定本次快照的 `viking://` URI 列表,条目可以是文件或目录;目录会按照快照的剪枝规则递归展开。`null` 表示对整棵账号树做快照。传入空列表 `[]` 表示显式的空路径集(不会产生改动)。如果某个路径在 VFS 和前一次快照中都不存在,会输出一条 warn,并按"对该名称下任何子树执行删除"处理 |+| branch | str | 否 | `main` | 要推进的分支 |+| author_name | str | 否 | null | 覆盖默认的提交者名字(默认 `viking-bot`) |+| author_email | str | 否 | null | 覆盖默认的提交者邮箱 |++**Python SDK (Embedded / HTTP)**++```python+result = client.snapshot.commit(+ message="v1 initial import",+ paths=["viking://resources/my_md.md"],+)+print(result["commit_oid"])+```++**HTTP API**++```+POST /api/v1/snapshot/commit+```++```bash+curl -X POST "http://localhost:1933/api/v1/snapshot/commit" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "message": "v1 initial import",+ "paths": ["viking://resources/my_md.md"]+ }'+```++**CLI**++```bash+ov snapshot commit -m "v1 initial import" --paths viking://resources/my_md.md -o json+```++**响应**++新建快照时:++```json+{+ "status": "ok",+ "result": {+ "result": "created",+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "changed": 3+ }+}+```++当工作区相对上一次提交没有任何变化时返回 `noop`,`commit_oid` 为当前 HEAD:++```json+{+ "status": "ok",+ "result": {+ "result": "noop",+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ }+}+```++---++### log()++从某个分支的 HEAD 开始,沿首个父提交(`parents[0]`)逐层回溯历史,按时间从新到旧返回提交列表。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| branch | str | 否 | `main` | 要回溯的分支 |+| limit | int | 否 | 20 | 最多返回的提交数量。HTTP 接口限制范围为 1–500 |++**Python SDK (Embedded / HTTP)**++```python+history = client.snapshot.log(limit=10)+for commit in history:+ print(commit["oid"], commit["message"])+```++**HTTP API**++```+GET /api/v1/snapshot/log?branch={branch}&limit={limit}+```++```bash+curl -X GET "http://localhost:1933/api/v1/snapshot/log?branch=main&limit=10" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot log --limit 10 -o json+```++**响应**++`result` 是一个提交元数据列表,每个元素与 [show()](#show) 返回的提交元数据结构相同:++```json+{+ "status": "ok",+ "result": [+ {+ "oid": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "tree": "11223344556677889900aabbccddeeff00112233",+ "parents": ["3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"],+ "author": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750300000,+ "tz_offset_seconds": 28800+ },+ "committer": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750300000,+ "tz_offset_seconds": 28800+ },+ "message": "v2 modify delete add"+ }+ ]+}+```++> 当分支还没有任何提交时,HTTP 接口返回 `404 NOT_FOUND`。++---++### show()++查看某个提交的元数据;如果同时指定 `path`,则返回该提交中对应文件的内容。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| target_ref | str | 是 | - | 提交 OID(支持缩写前缀)、分支名或标签 |+| path | str | 否 | null | 某个文件的 `viking://` URI;省略时返回提交元数据 |++**Python SDK (Embedded / HTTP)**++```python+# 查看提交元数据+meta = client.snapshot.show("3f2a1b9c")+print(meta["message"], meta["parents"])++# 读取该提交中某个文件的内容+blob = client.snapshot.show("3f2a1b9c", path="viking://resources/my_project/guide.md")+```++> 注意:带 `path` 读取文件内容时,**Embedded(本地)客户端**直接返回原始 `bytes`;**HTTP 客户端**返回 `{"oid": str, "size": int, "bytes": bytes}` 字典。++**HTTP API**++```+GET /api/v1/snapshot/show?target_ref={ref}[&path={uri}]+```++```bash+# 提交元数据(返回 JSON)+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=3f2a1b9c" \+ -H "X-API-Key: your-key"++# 读取文件内容(返回二进制流)+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=3f2a1b9c&path=viking://resources/my_project/guide.md" \+ -H "X-API-Key: your-key"+```++不带 `path` 时返回提交元数据 JSON;带 `path` 时返回原始字节流(`Content-Type: application/octet-stream`),并附带两个响应头:++- `X-Snapshot-Oid`:blob 对象的 OID+- `X-Snapshot-Size`:blob 字节数++**CLI**++```bash+# 提交元数据+ov snapshot show 3f2a1b9c -o json++# 读取文件内容(默认输出到 stdout,可用 --out-file 写入本地文件)+ov snapshot show 3f2a1b9c --path viking://resources/my_project/guide.md --out-file ./guide.md+```++**响应(提交元数据)**++```json+{+ "status": "ok",+ "result": {+ "oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "tree": "00112233445566778899aabbccddeeff00112233",+ "parents": [],+ "author": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750299000,+ "tz_offset_seconds": 28800+ },+ "committer": {+ "name": "viking-bot",+ "email": "[email protected]",+ "time_seconds": 1750299000,+ "tz_offset_seconds": 28800+ },+ "message": "v1 initial import"+ }+}+```++---++### restore()++把某个目录(或整棵账号树)恢复到 `source_commit` 时的状态。++这是**正向恢复**:它会计算 `source_commit` 与当前 HEAD 之间的差异并写回工作区,然后在当前 HEAD 之上生成一个**新的提交**。新提交的父提交是恢复前的 HEAD(而非 `source_commit`),历史不会被改写。`project_dir` 之外的文件保持不变。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| source_commit | str | 是 | - | 要恢复到的来源:提交 OID(支持缩写前缀)、分支名或标签 |+| project_dir | str | 否 | null | 要恢复的子目录 `viking://` URI;省略时恢复整棵账号树 |+| branch | str | 否 | `main` | 要推进的分支 |+| dry_run | bool | 否 | false | 仅计算并返回差异,不做任何写入 |+| message | str | 否 | null | 新提交的说明;省略时自动生成 |+| author_name | str | 否 | null | 覆盖默认的提交者名字 |+| author_email | str | 否 | null | 覆盖默认的提交者邮箱 |++**Python SDK (Embedded / HTTP)**++```python+result = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ message="restore to v1",+)+print(result["result"], result["new_commit_oid"])++# 先预演,确认要改动哪些文件+plan = client.snapshot.restore(+ project_dir="viking://resources/my_project",+ source_commit="3f2a1b9c",+ dry_run=True,+)+print(plan["diff"])+```++**HTTP API**++```+POST /api/v1/snapshot/restore+```++```bash+curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "project_dir": "viking://resources/my_project",+ "source_commit": "3f2a1b9c",+ "message": "restore to v1"+ }'+```++**CLI**++```bash+# 位置参数依次为 <source_commit> <project_dir>+ov snapshot restore 3f2a1b9c viking://resources/my_project -m "restore to v1" -o json++# 预演+ov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json+```++**响应(applied)**++成功写入并生成新提交时,`result` 为 `applied`。注意 `parent_commit` 等于恢复前的旧 HEAD,印证了正向恢复语义:++```json+{+ "status": "ok",+ "result": {+ "result": "applied",+ "new_commit_oid": "c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f50",+ "source_commit": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "parent_commit": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "written": 1,+ "deleted": 1,+ "unchanged": 1,+ "written_paths": ["resources/my_project/guide.md"],+ "deleted_paths": ["resources/my_project/changelog.md"],+ "task_id": "snapshot_restore_reindex-..."+ }+}+```++当恢复产生向量副作用(写入/删除文件)时,响应会附带一个 `task_id`,可通过 `GET /api/v1/tasks/{task_id}` 轮询后台向量重建进度。++**响应(noop)**++来源与当前状态字节级一致、无需改动时返回 `noop`,不生成新提交:++```json+{+ "status": "ok",+ "result": {+ "result": "noop",+ "head": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "source": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ }+}+```++**响应(dry_run)**++`dry_run=true` 时只返回计划差异,不做任何写入。差异中的路径均相对于 `project_dir`:++```json+{+ "status": "ok",+ "result": {+ "result": "dry_run",+ "head": "9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3",+ "source": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "diff": {+ "to_write": [{"path": "guide.md", "oid": "..."}],+ "to_delete": ["changelog.md"],+ "unchanged": ["notes/todo.md"]+ }+ }+}+```++## 典型流程++下面演示一个"提交 → 修改 → 恢复"的完整流程(Python SDK):++```python+import openviking as ov++client = ov.OpenViking()+client.initialize()++root = "viking://resources/my_project"++# 1. 写入初始内容并提交 v1+client.write(f"{root}/guide.md", "# Guide\n\nv1 content\n", mode="create", wait=True)+v1 = client.snapshot.commit(message="v1 initial import")++# 2. 修改后再提交 v2+client.write(f"{root}/guide.md", "# Guide\n\nv2 content\n", mode="replace", wait=True)+v2 = client.snapshot.commit(message="v2 update")++# 3. 查看历史+for c in client.snapshot.log(limit=10):+ print(c["oid"][:8], c["message"])++# 4. 把工作区恢复到 v1(会在 v2 之上生成一个新提交)+client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], message="restore to v1")++client.close()+```++更多端到端示例参见仓库中的 [examples/snapshot/](file:///cloudide/workspace/OpenViking/examples/snapshot) 目录,涵盖 SDK、HTTP、CLI 三种调用方式。++## 错误处理++| 场景 | HTTP 状态码 | 错误码 |+|------|-------------|--------|+| 分支/提交不存在,或 `show` 的 `path` 在该提交中不存在 | 404 | `NOT_FOUND` |+| 恢复期间分支被并发提交改写(CAS 冲突) | 409 | `CONFLICT` |+| 请求体包含未知字段(请求模型为 `extra="forbid"`) | 400 | `INVALID_ARGUMENT` |++## 相关文档++- [文件系统](03-filesystem.md):快照建立在文件系统资源之上+- [系统](07-system.md):通过 `GET /api/v1/tasks/{task_id}` 跟踪 restore 触发的后台向量重建+- [API 概览](01-overview.md):完整端点总览diff --git a/docs/zh/guides/13-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.mdsimilarity index 100%rename from docs/zh/guides/13-ragfs-cache.mdrename to docs/zh/guides/14-ragfs-cache.mddiff --git a/docs/zh/guides/15-snapshot.md b/docs/zh/guides/15-snapshot.mdnew file mode 100644index 000000000..6a6446832--- /dev/null+++ b/docs/zh/guides/15-snapshot.md@@ -0,0 +1,228 @@+# 多版本管理(快照)指南++本指南介绍如何启用并使用 OpenViking 的多版本管理(快照)能力。多版本管理在 VikingFS 之上提供基于 Git 的 `commit`/`log`/`show`/`restore` 原语,让你把账号下的资源树保存成一系列不可变快照,随时回溯历史、对比版本,并把工作区恢复到任意历史状态。++多版本管理由内嵌在 Rust RAGFS 层的 [gitoxide](https://github.com/Byron/gitoxide) 驱动,以 `account_id` 为粒度维护一个逻辑 Git 仓库(每个账号一个仓库),对调用方完全透明——你无需手动执行任何 `git` 命令。++> 关于各命令参数和响应结构的完整 API 参考,见 [多版本管理 API](../api/11-snapshot.md)。++## 前置条件++- 已有可用的 `ov.conf`。+- 已确认资源的读写正常(多版本管理建立在文件系统资源之上)。+- 如果选择 S3 后端存放 Git 对象,已准备好 bucket、region、endpoint 和访问凭据。++## 启用多版本管理++多版本管理默认**开启**(`git.enabled` 默认为 `true`)。Git 对象的存储后端可以选择 `local`(本地文件系统)或 `s3`(S3 兼容对象存储);当不显式设置 `git.backend` 时,会**自动继承 `storage.agfs.backend`**(`storage.agfs.backend` 为 `memory` 时映射为 `local`)。如需关闭多版本管理,把 `git.enabled` 设为 `false` 即可。++### 本地后端(推荐用于单机部署)++```json+{+ "storage": {+ "workspace": "./data"+ },+ "git": {+ "enabled": true,+ "backend": "local",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "local": {+ "base_dir": "",+ }+ }+}+```++配置说明:++| 字段 | 默认值 | 说明 |+|------|--------|------|+| `git.enabled` | `true` | 是否启用多版本管理。设为 `false` 可关闭快照功能 |+| `git.backend` | 继承 `storage.agfs.backend` | Git 对象后端:`local` 或 `s3`。不显式设置时继承 `storage.agfs.backend`(`memory` 映射为 `local`) |+| `git.default_branch` | `main` | 未显式指定时使用的默认分支名 |+| `git.author_name` | `viking-bot` | 调用方未传 `author_name` 时使用的默认提交者名字 |+| `git.author_email` | `[email protected]` | 默认提交者邮箱 |+| `git.local.base_dir` | `""` | Git 对象/引用的存放目录。**留空时默认使用 `{storage.workspace}/.ovgit`** |++> 通常把 `git.local.base_dir` 留空即可,让快照数据自动落在工作区下的 `.ovgit` 目录,便于和资源数据一起备份与迁移。++### S3 后端(推荐用于分布式/云端部署)++把 Git 对象与引用存到 S3 兼容对象存储(如火山引擎 TOS、MinIO、AWS S3)。当 `backend` 为 `s3` 时,**必须**提供 `git.s3` 段,且 `bucket`、`region` 不能为空。++> 提示:`git.s3` 的 `bucket`、`region`、`endpoint`、`access_key`、`secret_key` 在未显式设置时会**自动继承 `storage.agfs.s3`** 的对应字段。因此当 `storage.agfs` 已经配置为 s3 后端时,通常无需重复填写 `git.s3`——只要不显式设置 `git.backend`,多版本管理会直接复用 `storage.agfs` 的 bucket 与访问凭据。++```json+{+ "storage": {+ "workspace": "./data"+ },+ "git": {+ "enabled": true,+ "backend": "s3",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "s3": {+ "bucket": "your-tos-bucket",+ "region": "cn-beijing",+ "endpoint": "https://tos-s3-cn-beijing.volces.com",+ "access_key": "<your-volcengine-ak>",+ "secret_key": "<your-volcengine-sk>",+ "prefix": ".ovgit",+ "use_path_style": false,+ "cas_mode": "native"+ }+ }+}+```++配置说明:++| 字段 | 默认值 | 说明 |+|------|--------|------|+| `git.s3.bucket` | 继承 `storage.agfs.s3.bucket` | 存放 Git 对象/引用的 bucket,必填(可由 `storage.agfs.s3` 继承) |+| `git.s3.region` | 继承 `storage.agfs.s3.region`,否则 `us-east-1` | bucket 所在区域,必填 |+| `git.s3.prefix` | `.ovgit` | 键前缀,所有数据存放在 `{prefix}/{account}/...` 下 |+| `git.s3.endpoint` | 继承 `storage.agfs.s3.endpoint`,否则 `""` | 自定义 S3 端点(MinIO/TOS 等);标准 AWS S3 留空 |+| `git.s3.access_key` / `git.s3.secret_key` | 继承 `storage.agfs.s3` 对应字段,否则 `null` | 直接读取的凭据;留空则走 SDK 默认凭据链 |+| `git.s3.use_path_style` | `true` | `true` 用 path-style 寻址(MinIO 等);`false` 用 virtual-host 寻址(TOS 等) |+| `git.s3.cas_mode` | `native` | 引用 CAS 模式。`native` 使用 S3 条件写(If-Match) |++修改配置后,重启 OpenViking 服务(或重新初始化 SDK 客户端)使其生效。++> 仓库中提供了可直接参考的完整示例:[ov.conf.git-local.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-local.example) 与 [ov.conf.git-s3-tos.example](file:///cloudide/workspace/OpenViking/examples/snapshot/ov.conf.git-s3-tos.example)。++## 目录结构变化:`.ovgit` 目录++启用 `local` 后端且 `base_dir` 留空时,OpenViking 会在工作区下新增一个 **`.ovgit`** 目录用于存放 Git 对象和引用:++```text+data/ # storage.workspace+├── viking/ # 用户可见的资源树(viking:// 映射到这里)+│ └── ...+└── .ovgit/ # 多版本管理数据(新增)+ └── {account_id}/ # 每个账号一个逻辑 Git 仓库+ ├── objects/ # Git 对象(commit/tree/blob),标准 fanout 布局 aa/bb...+ ├── refs/+ │ └── heads/+ │ └── main # 分支引用,内容为 40 位十六进制 OID+ └── HEAD # 当前分支指针,内容为 "ref: refs/heads/main"+```++要点:++- `.ovgit` 是内部数据目录,**不会**通过 `viking://` 暴露,用户在文件系统 API(`ls`/`read` 等)中看不到也无法修改它。+- 它与 Git 的标准对象库布局一致(内容寻址的 `objects/`、loose 引用的 `refs/`),但由 OpenViking 自动管理,**无需也不应**手动运行 `git` 命令去操作它。+- 备份或迁移工作区时,把 `.ovgit` 一并复制即可保留完整的版本历史。+- 选择 `s3` 后端时,不会创建本地 `.ovgit` 目录,数据改为存放在 bucket 的 `{prefix}/{account}/...` 键下。++## 使用方法++启用后,三种调用方式都会出现快照相关命令。下面以一个"提交 → 修改 → 恢复"的最小流程演示。++### Python SDK++快照方法挂在 `client.snapshot.*` 命名空间下。++```python+import openviking as ov++client = ov.OpenViking()+client.initialize()++root = "viking://resources/my_project"++# 1. 写入初始内容并提交 v1+client.write(f"{root}/guide.md", "# Guide\n\nv1 content\n", mode="create", wait=True)+v1 = client.snapshot.commit(message="v1 initial import")+print("v1:", v1["commit_oid"])++# 2. 修改后再提交 v2+client.write(f"{root}/guide.md", "# Guide\n\nv2 content\n", mode="replace", wait=True)+v2 = client.snapshot.commit(message="v2 update")++# 3. 查看历史+for c in client.snapshot.log(limit=10):+ print(c["oid"][:8], c["message"])++# 4. 查看某个提交的元数据+print(client.snapshot.show(v1["commit_oid"])["message"])++# 5. 把工作区恢复到 v1(会在 v2 之上生成一个新的“正向”提交)+client.snapshot.restore(project_dir=root, source_commit=v1["commit_oid"], message="restore to v1")++client.close()+```++### CLI++CLI 子命令位于 `ov snapshot` 下:++```bash+# 提交当前工作区状态+ov snapshot commit -m "v1 initial import" -o json++# 回溯历史(最新在前)+ov snapshot log --limit 10 -o json++# 查看提交元数据+ov snapshot show <commit_oid> -o json++# 读取某个提交中的文件内容(默认输出到 stdout,可用 --out-file 写入本地文件)+ov snapshot show <commit_oid> --path viking://resources/my_project/guide.md --out-file ./guide.md++# 把目录恢复到某个历史快照(位置参数依次为 <source_commit> <project_dir>)+ov snapshot restore <commit_oid> viking://resources/my_project -m "restore to v1" -o json++# 先预演,确认会改动哪些文件+ov snapshot restore <commit_oid> viking://resources/my_project --dry-run -o json+```++### HTTP API++```bash+# 提交+curl -X POST "http://localhost:1933/api/v1/snapshot/commit" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"message": "v1 initial import"}'++# 回溯历史+curl -X GET "http://localhost:1933/api/v1/snapshot/log?branch=main&limit=10" \+ -H "X-API-Key: your-key"++# 查看提交元数据+curl -X GET "http://localhost:1933/api/v1/snapshot/show?target_ref=<commit_oid>" \+ -H "X-API-Key: your-key"++# 恢复+curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"project_dir": "viking://resources/my_project", "source_commit": "<commit_oid>", "message": "restore to v1"}'+```++## 重要语义:正向恢复++`restore` 采用**正向恢复(forward-commit)**:它读取 `source_commit` 的内容,把差异写回工作区,并在**当前 HEAD 之上生成一个新的提交**。因此:++- 新提交的父提交是恢复操作发生前的 HEAD,**不是** `source_commit`。+- HEAD 始终单调向前推进,**历史永远不会被改写或丢失**——回到旧版本本身也是一次新的提交。+- `restore` 只影响 `project_dir`(省略时为整棵账号树)范围内的文件,范围之外的文件保持不变。++## 注意事项++- 修改 `git` 配置后必须重启服务 / 重新初始化客户端才能生效。+- 启用 `s3` 后端时,`git.s3.bucket` 与 `git.s3.region` 为必填项,缺失会导致初始化失败。+- 恢复操作如涉及向量副作用(写入/删除文件),响应会返回一个 `task_id`,可通过 `GET /api/v1/tasks/{task_id}` 轮询后台向量重建进度(参见 [系统指南](05-observability.md) 与 [API 概览](../api/01-overview.md))。+- 不要手动用外部 `git` 工具去操作 `.ovgit` 目录,它由 OpenViking 维护。++## 相关文档++- [多版本管理 API](../api/11-snapshot.md):命令参数与响应的完整参考+- [配置说明](01-configuration.md):`ov.conf` 完整配置项+- [多写存储指南](13-multi-write-storage.md):资源数据的多后端复制diff --git a/examples/snapshot/ov.conf.git-local.example b/examples/snapshot/ov.conf.git-local.examplenew file mode 100644index 000000000..46d0de819--- /dev/null+++ b/examples/snapshot/ov.conf.git-local.example@@ -0,0 +1,37 @@+{+ "storage": {+ "workspace": "./data"+ },+ "embedding": {+ "dense": {+ "model": "doubao-embedding-vision-251215",+ "api_key": "{your-api-key}",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "dimension": 1024,+ "provider": "volcengine",+ "input": "multimodal"+ }+ },+ "vlm": {+ "model": "doubao-seed-2-0-pro-260215",+ "api_key": "{your-api-key}",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "temperature": 0.0,+ "max_retries": 2,+ "provider": "volcengine",+ "thinking": false+ },+ "server": {+ "host": "127.0.0.1"+ },+ "git": {+ "enabled": true,+ "backend": "local",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "local": {+ "base_dir": ""+ }+ }+}diff --git a/examples/snapshot/ov.conf.git-s3-tos.example b/examples/snapshot/ov.conf.git-s3-tos.examplenew file mode 100644index 000000000..50f5b0b34--- /dev/null+++ b/examples/snapshot/ov.conf.git-s3-tos.example@@ -0,0 +1,44 @@+{+ "storage": {+ "workspace": "./data"+ },+ "embedding": {+ "dense": {+ "model": "doubao-embedding-vision-251215",+ "api_key": "{your-api-key}",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "dimension": 1024,+ "provider": "volcengine",+ "input": "multimodal"+ }+ },+ "vlm": {+ "model": "doubao-seed-2-0-pro-260215",+ "api_key": "{your-api-key}",+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "temperature": 0.0,+ "max_retries": 2,+ "provider": "volcengine",+ "thinking": false+ },+ "server": {+ "host": "127.0.0.1"+ },+ "git": {+ "enabled": true,+ "backend": "s3",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "s3": {+ "bucket": "your-tos-bucket",+ "region": "cn-beijing",+ "endpoint": "https://tos-s3-cn-beijing.volces.com",+ "access_key": "<your-volcengine-ak>",+ "secret_key": "<your-volcengine-sk>",+ "prefix": ".ovgit",+ "use_path_style": false,+ "cas_mode": "native"+ }+ }+}\ No newline at end of filediff --git a/examples/snapshot/snapshot_cli_test.py b/examples/snapshot/snapshot_cli_test.pynew file mode 100644index 000000000..f379e915f--- /dev/null+++ b/examples/snapshot/snapshot_cli_test.py@@ -0,0 +1,218 @@+from __future__ import annotations++import json+import os+import subprocess+import time+import uuid+from pathlib import Path+from typing import Any++OVCLI_CONFIG_FILE = "/home/byteide/.openviking/ovcli.conf"+CLI_BIN = "ov"+WORKSPACE_URI = "viking://resources/snapshot_cli_demo"+COMMAND_TIMEOUT = 180+++def unique_run_uri() -> tuple[str, str]:+ run_id = f"{int(time.time())}_{uuid.uuid4().hex[:8]}"+ return run_id, f"{WORKSPACE_URI}_{run_id}"+++def resource_uris(root_uri: str) -> dict[str, str]:+ return {+ "guide": f"{root_uri}/guide.md",+ "todo": f"{root_uri}/notes/todo.md",+ "changelog": f"{root_uri}/changelog.md",+ "archive": f"{root_uri}/archive/old.md",+ }+++def print_section(title: str) -> None:+ print(f"\n{'=' * 20} {title} {'=' * 20}")+++def parse_json(stdout: str) -> dict[str, Any]:+ depth = 0+ start: int | None = None+ in_string = False+ escaped = False++ for index, char in enumerate(stdout):+ if start is None:+ if char == "{":+ start = index+ depth = 1+ continue++ if in_string:+ if escaped:+ escaped = False+ elif char == "\\":+ escaped = True+ elif char == '"':+ in_string = False+ continue++ if char == '"':+ in_string = True+ elif char == "{":+ depth += 1+ elif char == "}":+ depth -= 1+ if depth == 0:+ try:+ return json.loads(stdout[start : index + 1])+ except json.JSONDecodeError:+ return {}+ return {}+++def print_commit_oid(label: str, snapshot: dict[str, Any]) -> None:+ print(f"{label} commit_oid: {snapshot.get('commit_oid') or '<missing>'}")+++def show_snapshot(label: str, snapshot: dict[str, Any]) -> None:+ commit_oid = snapshot.get("commit_oid")+ if not commit_oid:+ raise RuntimeError(f"{label} snapshot output did not include commit_oid: {snapshot}")+ print(f"showing {label} commit_oid: {commit_oid}")+ run_ov(["snapshot", "show", commit_oid, "-o", "json"])+++def run_ov(args: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:+ env = os.environ.copy()+ env["OPENVIKING_CLI_CONFIG_FILE"] = str(Path(OVCLI_CONFIG_FILE).resolve())+ print(f"\n$ {CLI_BIN} {' '.join(args)}")+ proc = subprocess.run(+ [CLI_BIN] + args,+ capture_output=True,+ text=True,+ timeout=COMMAND_TIMEOUT,+ env=env,+ )+ print("--- stdout ---")+ print(proc.stdout.rstrip())+ print("--- stderr ---")+ print(proc.stderr.rstrip())+ if check and proc.returncode != 0:+ raise RuntimeError(f"command failed with exit code {proc.returncode}: {CLI_BIN} {' '.join(args)}")+ return proc+++def mkdir(uri: str) -> None:+ run_ov(["mkdir", uri, "-o", "json"])+++def write_text(uri: str, content: str, mode: str) -> None:+ run_ov(["write", uri, "--content", content, "--mode", mode, "--wait", "-o", "json"])+++def remove_resource(uri: str) -> None:+ run_ov(["rm", uri, "--wait", "-o", "json"])+++def print_find(query: str, root_uri: str) -> None:+ run_ov(["find", query, "--uri", root_uri, "--limit", "10", "-o", "json"])+++def commit_snapshot(message: str) -> dict[str, Any]:+ proc = run_ov(["snapshot", "commit", "-m", message, "-o", "json"])+ return parse_json(proc.stdout).get("result") or {}+++def get_task(task_id: str) -> dict[str, Any]:+ proc = run_ov(["task", "status", task_id, "-o", "json"])+ return parse_json(proc.stdout).get("result") or {}+++def wait_for_task(task_id: str | None, *, timeout: float = COMMAND_TIMEOUT, poll_interval: float = 0.5) -> None:+ """Poll a background task by id until it reaches a terminal state.++ restore schedules vectorization/indexing asynchronously and returns a+ ``task_id``; finding before that task completes can read stale vectors.+ """+ if not task_id:+ print("wait_for_task: no task_id (no vector side-effects to await)")+ return+ deadline = time.time() + timeout+ while True:+ task = get_task(task_id)+ status = task.get("status")+ if status in ("completed", "failed"):+ print(f"wait_for_task {task_id[:12]}: {status}")+ if status == "failed":+ raise RuntimeError(f"task {task_id} failed: {task.get('error')}")+ return+ if time.time() > deadline:+ raise TimeoutError(f"task {task_id} not complete after {timeout}s (status={status})")+ time.sleep(poll_interval)+++def main() -> None:+ run_id, root_uri = unique_run_uri()+ uris = resource_uris(root_uri)+ alpha = f"alpha_{run_id}"+ beta = f"beta_{run_id}"+ todo = f"todo_{run_id}"+ changelog = f"changelog_{run_id}"+ gamma = f"gamma_{run_id}"+ archive = f"archive_{run_id}"++ print_section("setup")+ print(f"config: {Path(OVCLI_CONFIG_FILE).resolve()}")+ print(f"workspace: {root_uri}")+ mkdir(root_uri)+ mkdir(f"{root_uri}/notes")++ print_section("v1 initial import")+ write_text(uris["guide"], f"# Guide\n\nInitial CLI content with {alpha}.\n", "create")+ write_text(uris["todo"], f"# Todo\n\nRemember {todo}.\n", "create")+ v1 = commit_snapshot("cli v1 initial import")+ print_commit_oid("v1", v1)+ print_find(alpha, root_uri)++ print_section("v2 modify delete add")+ write_text(uris["guide"], f"# Guide\n\nUpdated CLI content with {beta}.\n", "replace")+ remove_resource(uris["todo"])+ write_text(uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", "create")+ v2 = commit_snapshot("cli v2 modify delete add")+ print_commit_oid("v2", v2)+ print_find(beta, root_uri)+ print_find(todo, root_uri)+ print_find(changelog, root_uri)++ print_section("v3 second changes")+ mkdir(f"{root_uri}/archive")+ write_text(uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", "replace")+ write_text(uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", "create")+ v3 = commit_snapshot("cli v3 second changes")+ print_commit_oid("v3", v3)+ print_find(gamma, root_uri)+ print_find(archive, root_uri)+ run_ov(["snapshot", "log", "--limit", "10", "-o", "json"])+ show_snapshot("v1", v1)+ show_snapshot("v2", v2)+ show_snapshot("v3", v3)++ print_section("restore to v1")+ source_commit = v1.get("commit_oid")+ if not source_commit:+ raise RuntimeError(f"snapshot commit output did not include commit_oid: {v1}")+ restore_proc = run_ov(["snapshot", "restore", source_commit, root_uri, "-m", "cli restore to v1", "-o", "json"])+ restore = parse_json(restore_proc.stdout).get("result") or {}+ wait_for_task(restore.get("task_id"))+ run_ov(["ls", root_uri, "--recursive", "-o", "json"])+ run_ov(["read", uris["guide"]])+ run_ov(["read", uris["todo"]])+ print_find(alpha, root_uri)+ print_find(beta, root_uri)+ print_find(changelog, root_uri)+ run_ov(["snapshot", "log", "--limit", "10", "-o", "json"])++ print_section("done")+ print("CLI snapshot multi-version example finished")+++if __name__ == "__main__":+ main()diff --git a/examples/snapshot/snapshot_example.py b/examples/snapshot/snapshot_example.pynew file mode 100644index 000000000..7173f8a3c--- /dev/null+++ b/examples/snapshot/snapshot_example.py@@ -0,0 +1,184 @@+from __future__ import annotations++import os+import time+import uuid+from pathlib import Path+from typing import Any++OV_CONFIG_FILE = "/home/byteide/.openviking/ov.conf"+WORKSPACE_URI = "viking://resources/snapshot_sdk_demo"+WAIT_TIMEOUT = 180.0+++def unique_run_uri() -> tuple[str, str]:+ run_id = f"{int(time.time())}_{uuid.uuid4().hex[:8]}"+ return run_id, f"{WORKSPACE_URI}_{run_id}"+++def resource_uris(root_uri: str) -> dict[str, str]:+ return {+ "guide": f"{root_uri}/guide.md",+ "todo": f"{root_uri}/notes/todo.md",+ "changelog": f"{root_uri}/changelog.md",+ "archive": f"{root_uri}/archive/old.md",+ }+++def print_section(title: str) -> None:+ print(f"\n{'=' * 20} {title} {'=' * 20}")+++def short_oid(commit_oid: str | None) -> str:+ return commit_oid[:12] if commit_oid else "<none>"+++def write_text(client: Any, uri: str, content: str, mode: str) -> None:+ result = client.write(uri, content, mode=mode, wait=True, timeout=WAIT_TIMEOUT)+ print(f"write: {uri} (mode={result.get('mode')}, bytes={result.get('written_bytes')})")+++def remove_resource(client: Any, uri: str) -> None:+ client.rm(uri, wait=True, timeout=WAIT_TIMEOUT)+ print(f"rm: {uri}")+++def print_find(client: Any, query: str, root_uri: str) -> None:+ results = client.find(query, target_uri=root_uri, limit=10)+ if not results.resources:+ print(f"find {query!r}: (no matches)")+ return+ print(f"find {query!r}: {len(results.resources)} match(es)")+ for r in results.resources:+ print(f" {r.uri} (score: {r.score:.4f})")+++def print_read(client: Any, uri: str) -> None:+ content = client.read(uri)+ first_line = content.splitlines()[0] if content else ""+ print(f"read {uri}: {len(content)} chars | {first_line}")+++def commit_snapshot(client: Any, message: str) -> dict[str, Any]:+ result = client.snapshot.commit(message=message)+ print(f"commit {message!r}: result={result.get('result')} oid={short_oid(result.get('commit_oid'))}")+ return result+++def wait_for_task(+ client: Any,+ task_id: str | None,+ *,+ timeout: float = WAIT_TIMEOUT,+ poll_interval: float = 0.5,+) -> None:+ """Poll a background task by id until it reaches a terminal state.++ restore schedules vectorization/indexing asynchronously and returns a+ ``task_id``; finding before that task completes can read stale vectors.+ """+ if not task_id:+ print("wait_for_task: no task_id (no vector side-effects to await)")+ return+ deadline = time.time() + timeout+ while True:+ task = client.get_task(task_id) or {}+ status = task.get("status")+ if status in ("completed", "failed"):+ print(f"wait_for_task {task_id[:12]}: {status}")+ if status == "failed":+ raise RuntimeError(f"task {task_id} failed: {task.get('error')}")+ return+ if time.time() > deadline:+ raise TimeoutError(f"task {task_id} not complete after {timeout}s (status={status})")+ time.sleep(poll_interval)+++def main() -> None:+ os.environ["OPENVIKING_CONFIG_FILE"] = str(Path(OV_CONFIG_FILE).resolve())++ import openviking as ov++ run_id, root_uri = unique_run_uri()+ uris = resource_uris(root_uri)+ alpha = f"alpha_{run_id}"+ beta = f"beta_{run_id}"+ todo = f"todo_{run_id}"+ changelog = f"changelog_{run_id}"+ gamma = f"gamma_{run_id}"+ archive = f"archive_{run_id}"++ client = ov.OpenViking(path="./data")+ client.initialize()+ try:+ print_section("setup")+ print(f"config: {Path(OV_CONFIG_FILE).resolve()}")+ print(f"workspace: {root_uri}")+ client.mkdir(root_uri)+ client.mkdir(f"{root_uri}/notes")+ print(f"mkdir: {root_uri}, {root_uri}/notes")++ print_section("v1 initial import")+ write_text(client, uris["guide"], f"# Guide\n\nInitial SDK content with {alpha}.\n", mode="create")+ write_text(client, uris["todo"], f"# Todo\n\nRemember {todo}.\n", mode="create")+ v1 = commit_snapshot(client, "sdk v1 initial import")+ print_find(client, alpha, root_uri)++ print_section("v2 modify delete add")+ write_text(client, uris["guide"], f"# Guide\n\nUpdated SDK content with {beta}.\n", mode="replace")+ remove_resource(client, uris["todo"])+ write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", mode="create")+ v2 = commit_snapshot(client, "sdk v2 modify delete add")+ print_find(client, beta, root_uri)+ print_find(client, todo, root_uri)+ print_find(client, changelog, root_uri)++ print_section("v3 second changes")+ client.mkdir(f"{root_uri}/archive")+ print(f"mkdir: {root_uri}/archive")+ write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", mode="replace")+ write_text(client, uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", mode="create")+ v3 = commit_snapshot(client, "sdk v3 second changes")+ print_find(client, gamma, root_uri)+ print_find(client, archive, root_uri)+ log_before = client.snapshot.log(limit=10)+ print(f"snapshot log: {len(log_before)} commit(s)")+ for commit in log_before:+ print(f" {short_oid(commit.get('oid'))} {commit.get('message', '')}")+ for label, snap in (("v1", v1), ("v2", v2), ("v3", v3)):+ meta = client.snapshot.show(snap["commit_oid"])+ print(f"snapshot show {label}: oid={short_oid(meta.get('oid'))} message={meta.get('message', '')!r}")++ print_section("restore to v1")+ restore = client.snapshot.restore(+ project_dir=root_uri,+ source_commit=v1["commit_oid"],+ message="sdk restore to v1",+ )+ print(+ f"snapshot restore: result={restore.get('result')} oid={short_oid(restore.get('commit_oid'))} "+ f"written={len(restore.get('written_paths') or [])} deleted={len(restore.get('deleted_paths') or [])}"+ )+ wait_for_task(client, restore.get("task_id"))+ entries = client.ls(root_uri, recursive=True)+ print(f"ls after restore: {len(entries)} entry(ies)")+ for entry in entries:+ print(f" {entry.get('uri') if isinstance(entry, dict) else entry}")+ print_read(client, uris["guide"])+ print_read(client, uris["todo"])+ print_find(client, alpha, root_uri)+ print_find(client, beta, root_uri)+ print_find(client, changelog, root_uri)+ log_after = client.snapshot.log(limit=10)+ print(f"snapshot log after restore: {len(log_after)} commit(s)")+ for commit in log_after:+ print(f" {short_oid(commit.get('oid'))} {commit.get('message', '')}")++ print_section("done")+ print("Python SDK snapshot multi-version example finished")+ finally:+ client.close()+++if __name__ == "__main__":+ main()diff --git a/examples/snapshot/snapshot_http_api_test.py b/examples/snapshot/snapshot_http_api_test.pynew file mode 100644index 000000000..74306f658--- /dev/null+++ b/examples/snapshot/snapshot_http_api_test.py@@ -0,0 +1,231 @@+from __future__ import annotations++import pprint+import time+import uuid+from pathlib import Path+from typing import Any++import httpx++from openviking_cli.utils.config.ovcli_config import load_ovcli_config++OVCLI_CONFIG_FILE = "/home/byteide/.openviking/ovcli.conf"+WORKSPACE_URI = "viking://resources/snapshot_http_demo"+WAIT_TIMEOUT = 180.0+++def unique_run_uri() -> tuple[str, str]:+ run_id = f"{int(time.time())}_{uuid.uuid4().hex[:8]}"+ return run_id, f"{WORKSPACE_URI}_{run_id}"+++def resource_uris(root_uri: str) -> dict[str, str]:+ return {+ "guide": f"{root_uri}/guide.md",+ "todo": f"{root_uri}/notes/todo.md",+ "changelog": f"{root_uri}/changelog.md",+ "archive": f"{root_uri}/archive/old.md",+ }+++def print_section(title: str) -> None:+ print(f"\n{'=' * 20} {title} {'=' * 20}")+++def print_result(label: str, value: Any) -> None:+ print(f"\n--- {label} ---")+ pprint.pp(value, width=120)+++def build_headers(config: Any) -> dict[str, str]:+ headers = dict(config.extra_headers or {})+ if config.api_key:+ headers["X-API-Key"] = config.api_key+ if config.account:+ headers["X-OpenViking-Account"] = config.account+ if config.user:+ headers["X-OpenViking-User"] = config.user+ if config.actor_peer_id:+ headers["X-OpenViking-Actor-Peer"] = config.actor_peer_id+ return headers+++def request_json(client: httpx.Client, method: str, path: str, label: str | None = None, **kwargs: Any) -> dict[str, Any]:+ response = client.request(method, path, **kwargs)+ output_label = label or f"{method} {path}"+ print_result(f"{output_label} status", response.status_code)+ if response.headers.get("content-type", "").startswith("application/json"):+ data = response.json()+ print_result(f"{output_label} response", data)+ response.raise_for_status()+ return data+ print(response.text)+ response.raise_for_status()+ return {"raw": response.text}+++def mkdir(client: httpx.Client, uri: str) -> None:+ request_json(client, "POST", "/api/v1/fs/mkdir", json={"uri": uri})+++def write_text(client: httpx.Client, uri: str, content: str, mode: str) -> None:+ print(f"write: {uri}")+ print(content.rstrip())+ request_json(+ client,+ "POST",+ "/api/v1/content/write",+ json={"uri": uri, "content": content, "mode": mode, "wait": True},+ )+++def remove_resource(client: httpx.Client, uri: str) -> None:+ request_json(client, "DELETE", "/api/v1/fs", params={"uri": uri, "recursive": False, "wait": True})+++def read_text(client: httpx.Client, uri: str) -> None:+ request_json(client, "GET", "/api/v1/content/read", label=f"read content after restore: {uri}", params={"uri": uri})+++def print_find(client: httpx.Client, query: str, root_uri: str) -> None:+ request_json(+ client,+ "POST",+ "/api/v1/search/find",+ json={"query": query, "target_uri": root_uri, "limit": 10},+ )+++def commit_snapshot(client: httpx.Client, message: str) -> dict[str, Any]:+ data = request_json(+ client,+ "POST",+ "/api/v1/snapshot/commit",+ json={"message": message},+ )+ return data.get("result") or {}+++def show_snapshot(client: httpx.Client, target_ref: str) -> None:+ request_json(client, "GET", "/api/v1/snapshot/show", label=f"snapshot show {target_ref}", params={"target_ref": target_ref})+++def wait_for_task(client: httpx.Client, task_id: str | None, *, timeout: float = WAIT_TIMEOUT, poll_interval: float = 0.5) -> None:+ """Poll a background task by id until it reaches a terminal state.++ restore schedules vectorization/indexing asynchronously and returns a+ ``task_id``; finding before that task completes can read stale vectors.+ """+ if not task_id:+ print("wait_for_task: no task_id (no vector side-effects to await)")+ return+ deadline = time.time() + timeout+ while True:+ data = request_json(client, "GET", f"/api/v1/tasks/{task_id}", label=f"task status {task_id[:12]}")+ status = (data.get("result") or {}).get("status")+ if status in ("completed", "failed"):+ print(f"wait_for_task {task_id[:12]}: {status}")+ if status == "failed":+ raise RuntimeError(f"task {task_id} failed: {(data.get('result') or {}).get('error')}")+ return+ if time.time() > deadline:+ raise TimeoutError(f"task {task_id} not complete after {timeout}s (status={status})")+ time.sleep(poll_interval)+++def main() -> None:+ config_path = str(Path(OVCLI_CONFIG_FILE).resolve())+ config = load_ovcli_config(config_path)+ if config is None or not config.url:+ raise RuntimeError(f"missing url in {config_path}")++ run_id, root_uri = unique_run_uri()+ uris = resource_uris(root_uri)+ alpha = f"alpha_{run_id}"+ beta = f"beta_{run_id}"+ todo = f"todo_{run_id}"+ changelog = f"changelog_{run_id}"+ gamma = f"gamma_{run_id}"+ archive = f"archive_{run_id}"++ with httpx.Client(+ base_url=config.url.rstrip("/"),+ headers=build_headers(config),+ timeout=config.timeout,+ ) as client:+ print_section("setup")+ print(f"config: {config_path}")+ print(f"server: {config.url}")+ print(f"workspace: {root_uri}")+ mkdir(client, root_uri)+ mkdir(client, f"{root_uri}/notes")++ print_section("v1 initial import")+ write_text(client, uris["guide"], f"# Guide\n\nInitial HTTP content with {alpha}.\n", "create")+ write_text(client, uris["todo"], f"# Todo\n\nRemember {todo}.\n", "create")+ v1 = commit_snapshot(client, "http v1 initial import")+ print_find(client, alpha, root_uri)++ print_section("v2 modify delete add")+ write_text(client, uris["guide"], f"# Guide\n\nUpdated HTTP content with {beta}.\n", "replace")+ remove_resource(client, uris["todo"])+ write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", "create")+ v2 = commit_snapshot(client, "http v2 modify delete add")+ print_find(client, beta, root_uri)+ print_find(client, todo, root_uri)+ print_find(client, changelog, root_uri)++ print_section("v3 second changes")+ mkdir(client, f"{root_uri}/archive")+ write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", "replace")+ write_text(client, uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", "create")+ v3 = commit_snapshot(client, "http v3 second changes")+ print_find(client, gamma, root_uri)+ print_find(client, archive, root_uri)+ request_json(+ client,+ "GET",+ "/api/v1/snapshot/log",+ label="snapshot log before restore",+ params={"branch": "main", "limit": 10},+ )+ show_snapshot(client, v1.get("commit_oid", ""))+ show_snapshot(client, v2.get("commit_oid", ""))+ show_snapshot(client, v3.get("commit_oid", ""))++ print_section("restore to v1")+ restore = request_json(+ client,+ "POST",+ "/api/v1/snapshot/restore",+ label=f"restore workspace to v1 {v1.get('commit_oid')}",+ json={"project_dir": root_uri, "source_commit": v1.get("commit_oid"), "message": "http restore to v1"},+ )+ wait_for_task(client, (restore.get("result") or {}).get("task_id"))+ request_json(+ client,+ "GET",+ "/api/v1/fs/ls",+ label="list workspace after restore",+ params={"uri": root_uri, "recursive": True},+ )+ read_text(client, uris["guide"])+ read_text(client, uris["todo"])+ print_find(client, alpha, root_uri)+ print_find(client, beta, root_uri)+ print_find(client, changelog, root_uri)+ request_json(+ client,+ "GET",+ "/api/v1/snapshot/log",+ label="snapshot log after restore",+ params={"branch": "main", "limit": 10},+ )++ print_section("done")+ print("HTTP API snapshot multi-version example finished")+++if __name__ == "__main__":+ main()diff --git a/openviking/async_client.py b/openviking/async_client.pyindex 2276174cc..a0f427bfb 100644--- a/openviking/async_client.py+++ b/openviking/async_client.py@@ -64,6 +64,7 @@ class AsyncOpenViking:self.user = UserIdentifier.the_default_user()self._initialized = False+ self._snapshot: Optional["AsyncSnapshotNamespace"] = None# Mark initialized only after LocalClient is successfully constructed.self._singleton_initialized = False@@ -333,6 +334,18 @@ class AsyncOpenViking:def _service(self):return self._client.service+ @property+ def snapshot(self) -> "AsyncSnapshotNamespace":+ """Snapshot version control namespace.++ Lazy-initialized on first access so importing the client does not+ pull in the snapshot module when it's not needed.+ """+ if getattr(self, "_snapshot", None) is None:+ from openviking.snapshot_namespace import AsyncSnapshotNamespace+ self._snapshot = AsyncSnapshotNamespace(self)+ return self._snapshot+async def wait_processed(self, timeout: float = None) -> Dict[str, Any]:"""Wait for all queued processing to complete."""await self._ensure_initialized()diff --git a/openviking/client/local.py b/openviking/client/local.pyindex 2741a1cc5..1b0a04210 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -784,6 +784,68 @@ class LocalClient(BaseClient):vector_mode=vector_mode,)+ # ============= Git Version Control =============++ async def git_commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Create a git snapshot. See VikingFS.commit for semantics."""+ return await self._service.fs.commit(+ message=message,+ paths=paths,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ ctx=self._ctx,+ )++ async def git_restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Restore a subtree, or the full account tree when project_dir is omitted."""+ return await self._service.fs.restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ ctx=self._ctx,+ )++ async def git_show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ """Read a commit's metadata or a single blob."""+ return await self._service.fs.show(target_ref, path=path, ctx=self._ctx)++ async def git_log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ """Walk back along parents[0] up to limit commits."""+ return await self._service.fs.log(branch=branch, limit=limit, ctx=self._ctx)+# ============= Debug =============async def check_consistency(self, uri: str) -> Dict[str, Any]:diff --git a/openviking/pyagfs/__init__.py b/openviking/pyagfs/__init__.pyindex 7e0a07c37..42cb721f2 100644--- a/openviking/pyagfs/__init__.py+++ b/openviking/pyagfs/__init__.py@@ -34,6 +34,8 @@ from .exceptions import (AGFSPluginError,AGFSSerializationError,AGFSTimeoutError,+ GitConcurrentCommitError,+ GitRestoreWritebackPartialError,)from .helpers import cp, download, uploadfrom .protocols import AGFSSyncClientProtocol@@ -180,6 +182,8 @@ __all__ = ["AGFSNetworkError","AGFSInternalError","AGFSPluginError",+ "GitConcurrentCommitError",+ "GitRestoreWritebackPartialError","cp","upload","download",diff --git a/openviking/pyagfs/exceptions.py b/openviking/pyagfs/exceptions.pyindex 73fd756a3..36ec261f2 100644--- a/openviking/pyagfs/exceptions.py+++ b/openviking/pyagfs/exceptions.py@@ -133,3 +133,65 @@ class AGFSPluginError(AGFSClientError):"""Plugin error"""pass+++class GitConcurrentCommitError(AGFSClientError):+ """Raised when a git ref CAS update lost the race against another writer.++ The branch ref moved between the read-parent step and the cas_update step.+ Callers should refresh and retry, or surface the conflict to the user.+ """++ pass+++class GitRestoreWritebackPartialError(AGFSClientError):+ """Raised when ``git_restore`` advanced the branch ref to the new commit+ but at least one per-path VFS write or delete failed afterwards.++ The branch ref already points at ``new_commit_oid`` — the operation cannot+ be rolled back. Callers must:++ 1. Still trigger reindex for ``written_paths`` / ``deleted_paths`` (those+ did reach the VFS, so the vector index would otherwise stay stale).+ 2. Surface ``failed_writes`` / ``failed_deletes`` so the operator can+ retry or repair the affected paths.++ Native code constructs this with ``(message, payload_dict)``; callers may+ also build it from Python with no payload (defaults are zero-counts /+ empty lists). ``task_id`` is filled in by ``VikingFS.restore`` once the+ background reindex has been scheduled.+ """++ def __init__(self, message, payload=None):+ super().__init__(message)+ payload = payload or {}+ self.new_commit_oid = payload.get("new_commit_oid")+ self.source_commit = payload.get("source_commit")+ self.parent_commit = payload.get("parent_commit")+ self.written = payload.get("written", 0)+ self.deleted = payload.get("deleted", 0)+ self.unchanged = payload.get("unchanged", 0)+ self.written_paths = list(payload.get("written_paths") or [])+ self.deleted_paths = list(payload.get("deleted_paths") or [])+ # Each entry is a (path, error-message) pair; tuples in Rust marshal+ # to Python as tuples, but accept lists here too for tolerance.+ self.failed_writes = [tuple(p) for p in (payload.get("failed_writes") or [])]+ self.failed_deletes = [tuple(p) for p in (payload.get("failed_deletes") or [])]+ # Filled by ``VikingFS.restore`` after it schedules the reindex task.+ self.task_id = None++ def to_dict(self):+ return {+ "new_commit_oid": self.new_commit_oid,+ "source_commit": self.source_commit,+ "parent_commit": self.parent_commit,+ "written": self.written,+ "deleted": self.deleted,+ "unchanged": self.unchanged,+ "written_paths": self.written_paths,+ "deleted_paths": self.deleted_paths,+ "failed_writes": [list(p) for p in self.failed_writes],+ "failed_deletes": [list(p) for p in self.failed_deletes],+ "task_id": self.task_id,+ }diff --git a/openviking/server/app.py b/openviking/server/app.pyindex c978d19d0..41f9eb446 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -44,6 +44,7 @@ from openviking.server.routers import (search_router,sessions_router,skills_router,+ snapshot_router,stats_router,system_router,tasks_router,@@ -531,6 +532,7 @@ def create_app(app.include_router(privacy_configs_router)app.include_router(skills_router)app.include_router(sessions_router)+ app.include_router(snapshot_router)app.include_router(stats_router)app.include_router(pack_router)app.include_router(debug_router)diff --git a/openviking/server/dependencies.py b/openviking/server/dependencies.pyindex 1c9f11e74..16b506583 100644--- a/openviking/server/dependencies.py+++ b/openviking/server/dependencies.py@@ -27,11 +27,16 @@ def get_service() -> OpenVikingService:return _service-def set_service(service: OpenVikingService) -> None:- """Set the OpenVikingService instance.+def get_service_or_none() -> Optional[OpenVikingService]:+ """Return the registered OpenVikingService, or None if not set."""+ return _service+++def set_service(service: Optional[OpenVikingService]) -> None:+ """Set (or clear) the OpenVikingService instance.Args:- service: OpenVikingService instance to set+ service: OpenVikingService instance to register, or None to clear."""global _service_service = servicediff --git a/openviking/server/error_mapping.py b/openviking/server/error_mapping.pyindex 3b8157818..357478afc 100644--- a/openviking/server/error_mapping.py+++ b/openviking/server/error_mapping.py@@ -25,6 +25,7 @@ from openviking.pyagfs.exceptions import (AGFSPluginError,AGFSSerializationError,AGFSTimeoutError,+ GitConcurrentCommitError,)from openviking.storage.errors import LockAcquisitionError, ResourceBusyErrorfrom openviking_cli.exceptions import (@@ -447,6 +448,14 @@ def map_exception("retryable": True,}return OpenVikingError(str(exc), code="CONFLICT", details=details)+ if isinstance(exc, GitConcurrentCommitError):+ details = {+ "conflict_type": "git_ref_cas",+ "retryable": True,+ }+ return OpenVikingError(+ str(exc) or "concurrent git commit", code="CONFLICT", details=details+ )if isinstance(exc, PermissionError):return PermissionDeniedError(str(exc), resource=resource)if isinstance(exc, FileNotFoundError):diff --git a/openviking/server/models.py b/openviking/server/models.pyindex e998239d3..f04f7b79c 100644--- a/openviking/server/models.py+++ b/openviking/server/models.py@@ -49,5 +49,6 @@ ERROR_CODE_TO_HTTP_STATUS = {"SESSION_EXPIRED": 410,"UNSUPPORTED_URI": 400,"UNSUPPORTED_MODE": 400,+ "RESTORE_WRITEBACK_PARTIAL": 500,"UNKNOWN": 500,}diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.pyindex ded23d489..1fb22653a 100644--- a/openviking/server/routers/__init__.py+++ b/openviking/server/routers/__init__.py@@ -18,6 +18,7 @@ from openviking.server.routers.resources import router as resources_routerfrom openviking.server.routers.search import router as search_routerfrom openviking.server.routers.sessions import router as sessions_routerfrom openviking.server.routers.skills import router as skills_router+from openviking.server.routers.snapshot import router as snapshot_routerfrom openviking.server.routers.stats import router as stats_routerfrom openviking.server.routers.system import router as system_routerfrom openviking.server.routers.tasks import router as tasks_router@@ -37,6 +38,7 @@ __all__ = ["relations_router","sessions_router","skills_router",+ "snapshot_router","stats_router","pack_router","privacy_configs_router",diff --git a/openviking/server/routers/snapshot.py b/openviking/server/routers/snapshot.pynew file mode 100644index 000000000..ec7500a0e--- /dev/null+++ b/openviking/server/routers/snapshot.py@@ -0,0 +1,177 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""HTTP routes for git-style version control (snapshots).++Mirrors VikingFS.commit / VikingFS.restore / VikingFS.show / VikingFS.log,+which already implement the underlying semantics.+"""++from typing import List, Optional++from fastapi import APIRouter, Body, Depends, Query+from fastapi.responses import Response as FastAPIResponse+from pydantic import BaseModel, ConfigDict++from openviking.pyagfs.exceptions import (+ AGFSClientError,+ AGFSNotFoundError,+ GitRestoreWritebackPartialError,+)+from openviking.server.auth import get_request_context+from openviking.server.dependencies import get_service+from openviking.server.error_mapping import map_exception+from openviking.server.identity import RequestContext+from openviking.server.models import Response+from openviking_cli.exceptions import InternalError, NotFoundError, OpenVikingError++router = APIRouter(prefix="/api/v1/snapshot", tags=["snapshot"])+++class CommitRequest(BaseModel):+ """Request body for ``POST /api/v1/snapshot/commit``."""++ model_config = ConfigDict(extra="forbid")++ message: str+ paths: Optional[List[str]] = None+ branch: str = "main"+ author_name: Optional[str] = None+ author_email: Optional[str] = None++[email protected]("/commit")+async def commit(+ request: CommitRequest = Body(...),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Create a new snapshot of the current workspace state."""+ service = get_service()+ try:+ result = await service.fs.commit(+ message=request.message,+ paths=request.paths,+ branch=request.branch,+ author_name=request.author_name,+ author_email=request.author_email,+ ctx=_ctx,+ )+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ return Response(status="ok", result=result)++[email protected]("/log")+async def log(+ branch: str = Query("main", description="Branch ref name"),+ limit: int = Query(20, ge=1, le=500, description="Max commits to return"),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Walk commit history newest-first along parents[0]."""+ service = get_service()+ try:+ result = await service.fs.log(branch=branch, limit=limit, ctx=_ctx)+ except AGFSNotFoundError:+ raise NotFoundError(branch, "git_ref")+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ return Response(status="ok", result=result)+++class RestoreRequest(BaseModel):+ """Request body for ``POST /api/v1/snapshot/restore``."""++ model_config = ConfigDict(extra="forbid")++ project_dir: Optional[str] = None+ source_commit: str+ branch: str = "main"+ dry_run: bool = False+ message: Optional[str] = None+ author_name: Optional[str] = None+ author_email: Optional[str] = None++[email protected]("/restore")+async def restore(+ request: RestoreRequest = Body(...),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Forward-commit restore: rebuild project_dir from source_commit on top of HEAD."""+ service = get_service()+ try:+ result = await service.fs.restore(+ project_dir=request.project_dir,+ source_commit=request.source_commit,+ branch=request.branch,+ dry_run=request.dry_run,+ message=request.message,+ author_name=request.author_name,+ author_email=request.author_email,+ ctx=_ctx,+ )+ except AGFSNotFoundError as e:+ raise NotFoundError(request.source_commit, "git_ref") from e+ except GitRestoreWritebackPartialError as exc:+ # HEAD already advanced to the new commit, but some per-path VFS+ # writes/deletes failed. Surface structured diagnostics (including+ # task_id of the scheduled reindex) instead of collapsing to a+ # generic InternalError.+ raise OpenVikingError(+ f"snapshot restore partial: {exc}",+ code="RESTORE_WRITEBACK_PARTIAL",+ details=exc.to_dict(),+ ) from exc+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ except RuntimeError as e:+ # Fallback for the case where the native git binding cannot import+ # pyagfs and surfaces apply-phase failures as a bare RuntimeError.+ # With GitRestoreWritebackPartialError wired up, structured partial+ # failures now go through the branch above; this clause only catches+ # the degraded path.+ raise InternalError(+ f"snapshot restore failed: {e}", cause=e+ ) from e+ return Response(status="ok", result=result)++[email protected]("/show")+async def show(+ target_ref: str = Query(..., description="Commit oid, branch, or tag"),+ path: Optional[str] = Query(None, description="Optional viking:// URI for a single blob"),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Without ``path``: commit metadata JSON. With ``path``: raw blob bytes + X-Snapshot-* headers."""+ service = get_service()+ try:+ if path is None:+ result = await service.fs.show(target_ref, ctx=_ctx)+ return Response(status="ok", result=result)++ blob = await service.fs.show_blob_raw(target_ref, path=path, ctx=_ctx)+ except AGFSNotFoundError as e:+ resource = path if path is not None else target_ref+ raise NotFoundError(resource, "git_blob" if path is not None else "git_ref") from e+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise++ return FastAPIResponse(+ content=blob["bytes"],+ media_type="application/octet-stream",+ headers={+ "X-Snapshot-Oid": str(blob["oid"]),+ "X-Snapshot-Size": str(blob["size"]),+ },+ )diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 14281dd42..da57163b3 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -39,6 +39,7 @@ from openviking_cli.exceptions import NotInitializedErrorfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils import get_loggerfrom openviking_cli.utils.config import OPENVIKING_ENABLE_RECORDER_ENV, get_openviking_config+from openviking_cli.utils.config.git_config import GitConfigfrom openviking_cli.utils.config.open_viking_config import initialize_openviking_configfrom openviking_cli.utils.config.storage_config import StorageConfig@@ -118,6 +119,7 @@ class OpenVikingService:config.embedding.max_concurrent,config.vlm.max_concurrent,binding_config=binding_config,+ git_config=config.git,)# Initialize embedder@@ -132,13 +134,15 @@ class OpenVikingService:max_concurrent_embedding: int = 10,max_concurrent_semantic: int = 64,binding_config: Any = None,+ *,+ git_config: Optional[GitConfig] = None,) -> None:"""Initialize storage resources."""from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client# Create RAGFS client using utilityruntime_binding_config = binding_config or RagfsBindingConfig(agfs=config.agfs)- self._agfs_client = create_agfs_client(runtime_binding_config)+ self._agfs_client = create_agfs_client(runtime_binding_config, git_config=git_config)# Initialize QueueManager with agfs_clientif self._agfs_client:@@ -287,6 +291,7 @@ class OpenVikingService:self._config.embedding.max_concurrent,self._config.vlm.max_concurrent,binding_config=self._build_ragfs_binding_config(),+ git_config=self._config.git,)if self._embedder is None:@@ -412,6 +417,14 @@ class OpenVikingService:agfs_client=self._agfs_client,)+ # Register as the process-wide service so flows that resolve the+ # service via the dependency global (e.g. background reindex tasks+ # triggered by git restore) work in embedded mode, not just under the+ # HTTP server which calls set_service() during bootstrap.+ from openviking.server.dependencies import set_service++ set_service(self)+self._initialized = Truelogger.info("OpenVikingService initialized")@@ -448,6 +461,13 @@ class OpenVikingService:self._privacy_config_service = Noneself._initialized = False+ # Clear the process-wide registration if it still points at us, so a+ # closed service is never resolved via the dependency global.+ from openviking.server.dependencies import get_service_or_none, set_service++ if get_service_or_none() is self:+ set_service(None)+logger.info("OpenVikingService closed")async def reindex(diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pyindex 92995a21e..beb7960d6 100644--- a/openviking/service/fs_service.py+++ b/openviking/service/fs_service.py@@ -531,3 +531,90 @@ class FSService:recursive=recursive,ctx=ctx,)++ async def commit(+ self,+ *,+ message: str,+ ctx: RequestContext,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Forward to VikingFS.commit. See viking_fs.commit for semantics."""+ viking_fs = self._ensure_initialized()+ validated = (+ [validate_viking_uri(p) for p in paths] if paths is not None else None+ )+ return await viking_fs.commit(+ message=message,+ paths=validated,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ ctx=ctx,+ )++ async def restore(+ self,+ *,+ project_dir: Optional[str],+ source_commit: str,+ ctx: RequestContext,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Forward to VikingFS.restore. See viking_fs.restore for semantics."""+ viking_fs = self._ensure_initialized()+ if project_dir is not None:+ project_dir = validate_viking_uri(project_dir, field_name="project_dir")+ return await viking_fs.restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ ctx=ctx,+ )++ async def show(+ self,+ target_ref: str,+ ctx: RequestContext,+ *,+ path: Optional[str] = None,+ ) -> Any:+ """Forward to VikingFS.show. Returns dict (metadata) or bytes (blob)."""+ viking_fs = self._ensure_initialized()+ # validate_optional_viking_uri returns "" for None input; VikingFS.show needs None.+ path = validate_optional_viking_uri(path, field_name="path") or None+ return await viking_fs.show(target_ref, path=path, ctx=ctx)++ async def show_blob_raw(+ self,+ target_ref: str,+ ctx: RequestContext,+ *,+ path: str,+ ) -> Dict[str, Any]:+ """Forward to VikingFS.show_blob_raw. Returns ``{"oid", "size", "bytes"}``."""+ viking_fs = self._ensure_initialized()+ path = validate_viking_uri(path, field_name="path")+ return await viking_fs.show_blob_raw(target_ref, path=path, ctx=ctx)++ async def log(+ self,+ ctx: RequestContext,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ """Forward to VikingFS.log. Walks parents[0] up to limit commits."""+ viking_fs = self._ensure_initialized()+ return await viking_fs.log(branch=branch, limit=limit, ctx=ctx)diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.pyindex b3b9da79c..e3fd0c1b3 100644--- a/openviking/service/reindex_executor.py+++ b/openviking/service/reindex_executor.py@@ -712,6 +712,68 @@ class ReindexExecutor:counters.failed_records += 1counters.warnings.append(f"Failed to reindex {file_uri} vector: {exc}")+ async def reindex_directory_marker(+ self, *, dir_uri: str, level: ContextLevel, ctx: RequestContext+ ) -> None:+ """Recompute ONLY this directory's L0 (ABSTRACT) or L1 (OVERVIEW) vector.++ Non-recursive: does not touch descendants. Used by git restore when a+ directory's ``.abstract.md`` / ``.overview.md`` marker changed. When the+ on-disk semantic source is empty, the corresponding vector is deleted+ instead of upserted.+ """+ if level not in (ContextLevel.ABSTRACT, ContextLevel.OVERVIEW):+ raise ValueError(f"reindex_directory_marker only supports L0/L1, got {level!r}")+ if dir_uri == "viking://":+ return++ viking_fs = get_viking_fs()+ marker_name = ".abstract.md" if level == ContextLevel.ABSTRACT else ".overview.md"+ lock_path = viking_fs._uri_to_path(f"{dir_uri}/{marker_name}", ctx=ctx)+ async with LockContext(get_lock_manager(), [lock_path], lock_mode="exact"):+ abstract = await self._read_directory_abstract(dir_uri, ctx=ctx)+ if level == ContextLevel.ABSTRACT:+ vector_text = abstract+ else:+ overview = await self._read_directory_overview(dir_uri, ctx=ctx)+ vector_text = overview or abstract++ if not vector_text:+ await self.delete_uri_level(uri=dir_uri, level=level, ctx=ctx)+ return++ await self._upsert_context(+ uri=dir_uri,+ parent_uri=VikingURI(dir_uri).parent.uri,+ abstract=abstract,+ vector_text=vector_text,+ is_leaf=False,+ context_type=context_type_for_uri(dir_uri),+ level=level,+ ctx=ctx,+ )++ async def delete_uri_level(+ self, *, uri: str, level: ContextLevel, ctx: RequestContext+ ) -> int:+ """Delete ONLY the vector record at ``(uri, level)``. Returns count.++ Used by git restore for both directory markers (dir + L0/L1) and+ deleted source files (file + DETAIL).+ """+ service = get_service()+ assert service.vikingdb_manager is not None+ records = await service.vikingdb_manager.get_context_by_uri(+ uri=uri,+ level=int(level),+ limit=100,+ ctx=ctx,+ )+ ids = [str(rec["id"]) for rec in records if rec.get("id")]+ if not ids:+ return 0+ return await service.vikingdb_manager.delete(ids, ctx=ctx)+async def _reindex_user_namespace(self,*,diff --git a/openviking/snapshot_namespace.py b/openviking/snapshot_namespace.pynew file mode 100644index 000000000..ed6c7c37d--- /dev/null+++ b/openviking/snapshot_namespace.py@@ -0,0 +1,158 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Snapshot (multi-version) namespace for OpenViking clients.++Exposes the snapshot/versioning methods on BaseClient under a+`client.snapshot.*` namespace so the user-facing API reads as+`client.snapshot.commit(...)` rather than the flat `client.git_commit(...)`+underneath.+"""+from __future__ import annotations++from typing import Any, Dict, List, Optional, TYPE_CHECKING++from openviking_cli.utils import run_async++if TYPE_CHECKING:+ from openviking.async_client import AsyncOpenViking+ from openviking.sync_client import SyncOpenViking+++class AsyncSnapshotNamespace:+ """Snapshot version control methods on the async client.++ Forwards to the underlying BaseClient's git_* methods.+ """++ def __init__(self, client: "AsyncOpenViking"):+ self._client = client++ async def commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ await self._client._ensure_initialized()+ return await self._client._client.git_commit(+ message=message,+ paths=paths,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ )++ async def restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ await self._client._ensure_initialized()+ return await self._client._client.git_restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ )++ async def show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ await self._client._ensure_initialized()+ return await self._client._client.git_show(target_ref, path=path)++ async def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ await self._client._ensure_initialized()+ return await self._client._client.git_log(branch=branch, limit=limit)+++class SyncSnapshotNamespace:+ """Synchronous wrapper around AsyncSnapshotNamespace.++ Each method calls into the SyncOpenViking's underlying async client+ via run_async, matching the rest of the SyncOpenViking surface.+ """++ def __init__(self, client: "SyncOpenViking"):+ self._client = client++ def _ns(self) -> AsyncSnapshotNamespace:+ return self._client._async_client.snapshot++ def commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return run_async(+ self._ns().commit(+ message=message,+ paths=paths,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ )+ )++ def restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return run_async(+ self._ns().restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ )+ )++ def show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ return run_async(self._ns().show(target_ref, path=path))++ def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ return run_async(self._ns().log(branch=branch, limit=limit))diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex 97589a347..1ea9df3ca 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -31,6 +31,7 @@ from openviking.core.namespace import (is_hidden_by_actor_peer_view,may_include_hidden_actor_peers,)+from openviking.core.context import ContextLevelfrom openviking.core.namespace import (is_accessible as namespace_is_accessible,)@@ -283,6 +284,7 @@ class VikingFS:self._bound_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar("vikingfs_bound_ctx", default=None)+ self._background_tasks: set = set()@staticmethoddef _default_ctx() -> RequestContext:@@ -3320,3 +3322,565 @@ class VikingFS:except Exception as e:logger.error(f"[VikingFS] Failed to write {uri}: {e}")raise IOError(f"Failed to write {uri}: {e}")++ # ------------------------------------------------------------------+ # Git version control (commit / restore / show / log)+ # ------------------------------------------------------------------++ # First path segments that the Rust git enumerate.rs prunes from snapshots,+ # plus the runtime lock name. Mirrors INTERNAL_FIRST_SEGMENTS in+ # 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"}+ )++ _DEFAULT_GIT_AUTHOR_NAME = "viking-bot"+ _DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"++ def _uri_to_tree_path(self, uri: str, ctx: Optional[RequestContext] = None) -> str:+ """Convert a viking:// URI to an account-relative git tree path.++ ``viking://resources/proj_a/docs/a.md`` -> ``resources/proj_a/docs/a.md``.++ Pure prefix stripping: removes the ``viking://`` scheme and any+ ``/local/{account}/`` segment. Internal scopes that the Rust git layer+ would prune (`_system`, `tasks`, `temp`, `queue`, `upload`) and the+ runtime lock name (`.path.ovlock`) are rejected with ``ValueError``+ — passing them through silently would result in a no-op commit and+ confuse callers.+ """+ real_ctx = self._ctx_or_default(ctx)+ canonical = canonicalize_uri(uri, real_ctx)+ _, parts = self._normalized_uri_parts(canonical)+ if not parts:+ raise ValueError(+ f"git tree path cannot be the account root: {uri!r}"+ )+ first = parts[0]+ if first in self._GIT_INTERNAL_FIRST_SEGMENTS:+ raise ValueError(+ f"git tree path rejects internal scope/segment {first!r}: {uri!r}"+ )+ return "/".join(parts)++ def _tree_path_to_uri(self, tree_path: str) -> str:+ """Convert an account-relative git tree path to a viking:// URI.++ Inverse of :py:meth:`_uri_to_tree_path` (without context canonicalization).+ """+ cleaned = tree_path.strip("/")+ if not cleaned:+ raise ValueError("tree path must not be empty")+ return f"viking://{cleaned}"++ _DIR_MARKER_LEVELS = {+ ".abstract.md": ContextLevel.ABSTRACT,+ ".overview.md": ContextLevel.OVERVIEW,+ }+ _NO_VECTOR_DERIVED = frozenset({".relations.json"})++ def _classify_restore_path(+ self, tree_path: str, *, deleted: bool+ ) -> Optional[tuple]:+ """Classify a restore-affected tree path into a vector maintenance task.++ Returns a ``(op, uri, level)`` triple, or ``None`` when the path has no+ vector side-effect:++ - ``dir/.abstract.md`` / ``dir/.overview.md`` → recompute (write) or+ delete (removal) ONLY that directory's L0/L1 vector:+ ``("reindex_marker"|"delete", dir_uri, ABSTRACT|OVERVIEW)``.+ - ``.relations.json`` → ``None`` (not a vector text source).+ - anything else (a source file) → reindex (write) or delete (removal)+ its DETAIL vector:+ ``("reindex_file", file_uri, DETAIL)`` / ``("delete", file_uri, DETAIL)``.++ ``None`` is also returned for a directory marker at the account root+ (no parent directory to scope an L0/L1 vector to).+ """+ parent, _, name = tree_path.rpartition("/")+ if name in self._NO_VECTOR_DERIVED:+ return None+ level = self._DIR_MARKER_LEVELS.get(name)+ if level is not None:+ if not parent:+ return None+ dir_uri = self._tree_path_to_uri(parent)+ op = "delete" if deleted else "reindex_marker"+ return (op, dir_uri, level)+ # Source file.+ file_uri = self._tree_path_to_uri(tree_path)+ op = "delete" if deleted else "reindex_file"+ return (op, file_uri, ContextLevel.DETAIL)++ async def commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ctx: Optional[RequestContext] = None,+ ) -> Dict[str, Any]:+ """Create a git snapshot of the account's tree.++ Args:+ message: Commit message.+ paths: Optional list of ``viking://`` URIs to scope the commit to;+ entries may be files or directories. Directories are expanded+ recursively with the snapshot pruning rules applied. ``None``+ (default) enumerates the whole account tree. An empty list is+ forwarded as an explicit empty path list (no-op commit). A+ path that exists in neither the VFS nor the previous snapshot+ logs a warning and is treated as a no-op deletion.+ branch: Branch to advance. Defaults to ``"main"``.+ author_name / author_email: Override the default bot author.+ ctx: Request context (provides ``account_id``).++ Returns:+ Dict with ``result`` (``"created"`` / ``"noop"``) and ``commit_oid``;+ ``changed`` count when ``result == "created"``.+ """+ real_ctx = self._ctx_or_default(ctx)+ account = real_ctx.account_id+ if paths is None:+ tree_paths: Optional[List[str]] = None+ else:+ tree_paths = [self._uri_to_tree_path(p, ctx=real_ctx) for p in paths]+ return await self._async_agfs.run(+ "git_commit",+ account=account,+ branch=branch,+ message=message,+ paths=tree_paths,+ author_name=author_name or self._DEFAULT_GIT_AUTHOR_NAME,+ author_email=author_email or self._DEFAULT_GIT_AUTHOR_EMAIL,+ )++ async def restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ctx: Optional[RequestContext] = None,+ ) -> Dict[str, Any]:+ """Restore a project subtree to the state at ``source_commit``.++ Generates a new commit whose parent is the current HEAD (not the+ source commit) and writes the diff through the VFS. Paths outside+ ``project_dir`` are left untouched.++ Args:+ project_dir: ``viking://`` URI of the subtree, e.g.+ ``"viking://resources/proj_a"``. May also be passed as a+ short form like ``"resources/proj_a"``. Trailing slashes are+ stripped. Internal scopes are rejected with ``ValueError``.+ If None, restore the entire tree.+ source_commit: 40-hex OID, branch name, or full ref path.+ branch: Branch to advance. Defaults to ``"main"``.+ dry_run: If True, returns the planned diff without writing.+ message: Optional commit message; defaults to a generated string.+ author_name / author_email: Override the default bot author.+ ctx: Request context (provides ``account_id``).++ Returns:+ Dict containing ``result`` (``"applied"`` / ``"noop"`` / ``"dry_run"``)+ and corresponding oid / diff fields. When an ``Applied`` result has+ vector side-effects, a ``task_id`` is included for polling the+ background reindex via ``GET /api/v1/tasks/{task_id}``.++ After an ``Applied`` result, this method schedules background vector+ maintenance for the affected paths via :class:`ReindexExecutor`:+ directory markers (``.abstract.md`` / ``.overview.md``) recompute or+ delete only that directory's L0/L1 vector; source files reindex (write)+ or delete (removal) their DETAIL vector. ``.relations.json`` has no+ vector side-effect. The rebuild is tracked as a single task+ (``snapshot_restore_reindex``); per-path failures are logged and do not+ block the return value. The task reaches ``completed`` only after each+ affected vector has been written to (or deleted from) the index, so+ polling ``task_id`` to ``completed`` guarantees subsequent ``find``+ reads see the restored state.+ """+ real_ctx = self._ctx_or_default(ctx)+ account = real_ctx.account_id+ tree_dir: Optional[str]+ if project_dir is None:+ tree_dir = None+ else:+ tree_dir = self._uri_to_tree_path(project_dir, ctx=real_ctx).rstrip("/")+ if not tree_dir:+ raise ValueError(f"project_dir must not be empty: {project_dir!r}")+ # Build kwargs dynamically, only include project_dir if it's not None+ kwargs = {+ "account": account,+ "branch": branch,+ "source_commit": source_commit,+ "dry_run": dry_run,+ "message": message,+ "author_name": author_name or self._DEFAULT_GIT_AUTHOR_NAME,+ "author_email": author_email or self._DEFAULT_GIT_AUTHOR_EMAIL,+ }+ if tree_dir is not None:+ kwargs["project_dir"] = tree_dir+ # dry_run only computes the diff; it never writes the VFS, so it needs+ # no lock.+ if dry_run:+ return await self._async_agfs.run("git_restore", **kwargs)++ from openviking.storage.errors import LockAcquisitionError, ResourceBusyError+ from openviking.storage.transaction import LockContext, get_lock_manager+ from openviking.pyagfs.exceptions import GitRestoreWritebackPartialError++ # Serialize the writeback against concurrent VFS mutations on the same+ # subtree. A scoped restore tree-locks project_dir; a full restore+ # (project_dir is None) locks the account root so only one restore runs+ # per account at a time. The lock covers only the writeback — the+ # background reindex is scheduled after release, otherwise its per-path+ # child locks would conflict with this tree lock.+ lock_path = (+ self._uri_to_path(project_dir, ctx=real_ctx)+ if project_dir is not None+ else f"/local/{account}"+ )+ partial_exc: Optional[GitRestoreWritebackPartialError] = None+ try:+ async with LockContext(get_lock_manager(), [lock_path], lock_mode="tree"):+ try:+ result = await self._async_agfs.run("git_restore", **kwargs)+ except GitRestoreWritebackPartialError as exc:+ # The ref already advanced — capture the exception and+ # finish the lock scope cleanly. Reindex scheduling and+ # re-raise happen below, outside the tree lock.+ partial_exc = exc+ result = None+ except LockAcquisitionError:+ raise ResourceBusyError(+ f"Resource is being processed: {project_dir or '*'}",+ uri=project_dir or "*",+ )++ 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+ # the vector index doesn't stay stale, then re-raise so the caller+ # learns about the partial failure (and can inspect failed_writes+ # / failed_deletes / task_id on the exception).+ try:+ partial_exc.task_id = await self._schedule_restore_reindex_for_paths(+ written_paths=partial_exc.written_paths,+ deleted_paths=partial_exc.deleted_paths,+ project_dir=project_dir,+ real_ctx=real_ctx,+ )+ except Exception:+ logger.exception(+ "[VikingFS] git restore partial: reindex scheduling failed; "+ "HEAD advanced but reindex was not queued"+ )+ raise partial_exc++ if result.get("result") != "applied":+ return result++ written = list(result.get("written_paths") or [])+ deleted = list(result.get("deleted_paths") or [])+ if written or deleted:+ try:+ task_id = await self._schedule_restore_reindex_for_paths(+ written_paths=written,+ deleted_paths=deleted,+ project_dir=project_dir,+ real_ctx=real_ctx,+ )+ if task_id is not None:+ result["task_id"] = task_id+ except Exception:+ logger.exception(+ "[VikingFS] git restore reindex task creation failed; "+ "falling back to fire-and-forget rebuild"+ )+ self._schedule_vector_rebuild(+ written=written, deleted=deleted, ctx=real_ctx+ )+ return result++ async def _schedule_restore_reindex_for_paths(+ self,+ *,+ written_paths: List[str],+ deleted_paths: List[str],+ project_dir: Optional[str],+ real_ctx: RequestContext,+ ) -> Optional[str]:+ """Classify ``written``/``deleted`` paths into vector tasks and queue+ them as a single tracked background rebuild. Returns the task id, or+ ``None`` if there is nothing to do.++ Shared by the applied path and the partial-writeback recovery path —+ both schedule reindex for paths that actually reached the VFS.+ """+ if not written_paths and not deleted_paths:+ return None+ tasks = self._collect_restore_vector_tasks(written_paths, deleted_paths)+ if not tasks:+ return None++ from openviking.service.task_tracker import get_task_tracker++ tracker = get_task_tracker()+ task = await tracker.create(+ "snapshot_restore_reindex",+ resource_id=project_dir or "*",+ account_id=real_ctx.account_id,+ user_id=real_ctx.user.user_id,+ )+ await tracker.update_stage(+ task.task_id,+ "queued",+ account_id=real_ctx.account_id,+ user_id=real_ctx.user.user_id,+ )+ background = asyncio.create_task(+ self._run_restore_rebuild_tracked(task.task_id, tasks, real_ctx),+ name=f"vikingfs-git-restore-reindex:{task.task_id}",+ )+ self._background_tasks.add(background)+ background.add_done_callback(self._background_tasks.discard)+ return task.task_id++ async def show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ctx: Optional[RequestContext] = None,+ ) -> Union[Dict[str, Any], bytes]:+ """Read a commit's metadata or a single blob.++ ``path=None`` returns the commit metadata dict (oid, tree, parents,+ author, committer, message). ``path=str`` returns the blob bytes+ directly, stripping the oid/size envelope returned by the binding.+ """+ real_ctx = self._ctx_or_default(ctx)+ account = real_ctx.account_id+ tree_path = self._uri_to_tree_path(path, ctx=real_ctx) if path else None+ resp = await self._async_agfs.run(+ "git_show",+ account=account,+ target_ref=target_ref,+ path=tree_path,+ )+ if path is not None and isinstance(resp, dict) and "bytes" in resp:+ return resp["bytes"]+ return resp++ async def show_blob_raw(+ self,+ target_ref: str,+ *,+ path: str,+ ctx: Optional[RequestContext] = None,+ ) -> Dict[str, Any]:+ """Like ``show(target_ref, path=...)`` but returns the full envelope.++ Returns ``{"oid": str, "size": int, "bytes": bytes}`` without+ stripping. Used by the HTTP snapshot router to populate+ ``X-Snapshot-Oid`` / ``X-Snapshot-Size`` response headers.+ """+ real_ctx = self._ctx_or_default(ctx)+ account = real_ctx.account_id+ tree_path = self._uri_to_tree_path(path, ctx=real_ctx)+ resp = await self._async_agfs.run(+ "git_show",+ account=account,+ target_ref=target_ref,+ path=tree_path,+ )+ if not isinstance(resp, dict) or "bytes" not in resp:+ raise TypeError(+ f"git_show returned unexpected shape for blob path: {type(resp).__name__}"+ )+ return resp++ async def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ctx: Optional[RequestContext] = None,+ ) -> List[Dict[str, Any]]:+ """Walk back from ``branch``'s HEAD along ``parents[0]`` up to ``limit`` commits.++ Returns a list of commit metadata dicts (same shape as ``show(target_ref)``).+ """+ if limit <= 0:+ return []+ real_ctx = self._ctx_or_default(ctx)+ account = real_ctx.account_id+ head = await self._async_agfs.run(+ "git_show", account=account, target_ref=branch, path=None,+ )+ results: List[Dict[str, Any]] = [head]+ parents = head.get("parents") or []+ while parents and len(results) < limit:+ parent_oid = parents[0]+ commit = await self._async_agfs.run(+ "git_show", account=account, target_ref=parent_oid, path=None,+ )+ results.append(commit)+ parents = commit.get("parents") or []+ return results++ def _collect_restore_vector_tasks(+ self,+ written: List[str],+ deleted: List[str],+ ) -> set[tuple]:+ """Classify restore-affected paths into deduplicated ``(op, uri, level)`` tasks.++ Tasks are deduplicated on the exact ``(op, uri, level)`` key (no ancestor+ subsumption — each change is handled independently because no operation+ recurses into descendants).+ """+ tasks: set[tuple] = set()+ for tree_path in written:+ try:+ task = self._classify_restore_path(tree_path, deleted=False)+ except ValueError:+ continue+ if task is not None:+ tasks.add(task)+ for tree_path in deleted:+ try:+ task = self._classify_restore_path(tree_path, deleted=True)+ except ValueError:+ continue+ if task is not None:+ tasks.add(task)+ return tasks++ def _schedule_vector_rebuild(+ self,+ *,+ written: List[str],+ deleted: List[str],+ ctx: RequestContext,+ ) -> None:+ """Fire-and-forget precise vector maintenance for a git restore.++ Each affected path is classified by :py:meth:`_classify_restore_path`+ into a ``(op, uri, level)`` task and scheduled independently:++ - ``reindex_marker`` — recompute only a directory's L0/L1 vector.+ - ``reindex_file`` — recompute only a source file's DETAIL vector+ (non-recursive ``execute(mode="vectors_only")``).+ - ``delete`` — remove only the ``(uri, level)`` vector (directory+ marker removal, or deleted source file).++ Failures are logged and never propagate.+ """+ try:+ from openviking.service.reindex_executor import get_reindex_executor+ except Exception:+ logger.exception("[VikingFS] ReindexExecutor import failed; skipping rebuild")+ return++ try:+ loop = asyncio.get_running_loop()+ except RuntimeError:+ logger.warning(+ "[VikingFS] git restore vector rebuild skipped: no running event loop"+ )+ return++ tasks = self._collect_restore_vector_tasks(written, deleted)+ if not tasks:+ return++ executor = get_reindex_executor()+ for op, uri, level in tasks:+ loop.create_task(+ self._run_vector_rebuild(executor, op, uri, level, ctx),+ name=f"vikingfs-git-{op}:{uri}:{int(level)}",+ )++ async def _run_restore_rebuild_tracked(+ self,+ task_id: str,+ tasks: set[tuple],+ ctx: RequestContext,+ ) -> None:+ """Background worker driving a tracked restore vector rebuild.++ Runs all classified ``(op, uri, level)`` rebuild tasks concurrently and+ drives the task through start → complete/fail. Per-task failures are+ swallowed (and logged) inside :py:meth:`_run_vector_rebuild`, preserving+ the "failures do not block" semantics.+ """+ from openviking.service.task_tracker import get_task_tracker++ tracker = get_task_tracker()+ await tracker.start(+ task_id,+ account_id=ctx.account_id,+ user_id=ctx.user.user_id,+ stage="reindexing",+ )+ try:+ from openviking.service.reindex_executor import get_reindex_executor++ executor = get_reindex_executor()+ 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)},+ account_id=ctx.account_id,+ user_id=ctx.user.user_id,+ )+ except Exception as exc:+ await tracker.fail(+ task_id,+ str(exc),+ account_id=ctx.account_id,+ user_id=ctx.user.user_id,+ )++ async def _run_vector_rebuild(+ self,+ executor: Any,+ op: str,+ uri: str,+ level: ContextLevel,+ ctx: RequestContext,+ ) -> None:+ """Wrapper coroutine: dispatch one vector task and swallow errors."""+ try:+ if op == "reindex_marker":+ await executor.reindex_directory_marker(+ dir_uri=uri, level=level, ctx=ctx+ )+ elif op == "reindex_file":+ await executor.execute(+ uri=uri, mode="vectors_only", wait=True, ctx=ctx+ )+ elif op == "delete":+ await executor.delete_uri_level(uri=uri, level=level, ctx=ctx)+ else: # pragma: no cover - defensive+ logger.warning("[VikingFS] unknown vector rebuild op %r for %s", op, uri)+ except Exception:+ logger.exception(+ "[VikingFS] git restore vector task %s failed for %s", op, uri+ )diff --git a/openviking/sync_client.py b/openviking/sync_client.pyindex a7d60e072..877f2c5e3 100644--- a/openviking/sync_client.py+++ b/openviking/sync_client.py@@ -35,6 +35,7 @@ class SyncOpenViking:agent_id=agent_id,)self._initialized = False+ self._snapshot: Optional["SyncSnapshotNamespace"] = Nonedef initialize(self) -> None:"""Initialize OpenViking storage and indexes."""@@ -523,6 +524,14 @@ class SyncOpenViking:self.initialize()return self._async_client.observer+ @property+ def snapshot(self) -> "SyncSnapshotNamespace":+ """Snapshot version control namespace (synchronous)."""+ if getattr(self, "_snapshot", None) is None:+ from openviking.snapshot_namespace import SyncSnapshotNamespace+ self._snapshot = SyncSnapshotNamespace(self)+ return self._snapshot+@classmethoddef reset(cls) -> None:"""Reset singleton (for testing)."""diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex 7178ab425..b946af57e 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -400,13 +400,72 @@ def _serialize_redirect_policy(policy: Any) -> Dict[str, Any]:return _dump_config_object(policy)-def create_agfs_client(config: RagfsBindingConfig) -> Any:+def _build_git_config_dict(git_config: Any, storage_path: Path) -> Dict[str, Any]:+ """Build an in-memory git config dict consumed by the ragfs binding.++ The returned dict mirrors the Rust ``GitConfig`` serde struct so the binding+ deserializes it verbatim from the ``config["git"]`` section, without writing+ any TOML file. For ``backend == "local"`` a ``local`` sub-dict is emitted+ (defaulting ``base_dir`` to ``{storage_path}/.ovgit`` when empty); for+ ``backend == "s3"`` an ``s3`` sub-dict is emitted with keys matching the Rust+ ``GitS3ConfigPy`` struct.+ """+ backend = getattr(git_config, "backend", "local")+ result: Dict[str, Any] = {+ "enabled": bool(getattr(git_config, "enabled", False)),+ "backend": backend,+ "default_branch": getattr(git_config, "default_branch", "main"),+ "author_name": getattr(git_config, "author_name", "viking-bot"),+ "author_email": getattr(git_config, "author_email", "[email protected]"),+ }++ if backend == "s3":+ s3_cfg = getattr(git_config, "s3", None)+ if s3_cfg is None:+ raise ValueError("git backend 's3' requires a [git.s3] section")+ s3_dict: Dict[str, Any] = {+ "bucket": getattr(s3_cfg, "bucket", ""),+ "region": getattr(s3_cfg, "region", "us-east-1"),+ "prefix": getattr(s3_cfg, "prefix", ".ovgit"),+ "endpoint": getattr(s3_cfg, "endpoint", ""),+ "cas_mode": getattr(s3_cfg, "cas_mode", "native"),+ "use_path_style": bool(getattr(s3_cfg, "use_path_style", True)),+ }+ # Only emit credentials when provided; otherwise the binding falls back+ # to the SDK default credentials chain.+ access_key = getattr(s3_cfg, "access_key", None)+ secret_key = getattr(s3_cfg, "secret_key", None)+ if access_key:+ s3_dict["access_key"] = access_key+ if secret_key:+ s3_dict["secret_key"] = secret_key+ result["s3"] = s3_dict+ return result++ # Default: local backend+ local_cfg = getattr(git_config, "local", None)+ base_dir = getattr(local_cfg, "base_dir", "") if local_cfg is not None else ""+ if not base_dir:+ base_dir = str(storage_path / ".ovgit")+ else:+ base_dir = str(Path(base_dir).expanduser())++ result["local"] = {"base_dir": base_dir}+ return result+++def create_agfs_client(config: RagfsBindingConfig, *, git_config: Any = None) -> Any:"""Create a RAGFS client based on the provided configuration.Args:config: Single runtime config object containing both backend mount settings andconstruction-time binding sections.+ git_config: Optional GitConfig. When provided and ``enabled`` is True,+ the git config is built into an in-memory dict and injected into the+ binding ``config`` under the ``git`` key so the binding exposes git_*+ methods. No file is written to disk. When None or disabled, the client+ is constructed without a git section (legacy behavior).Returns:A RAGFSBindingClient instance.@@ -426,11 +485,20 @@ def create_agfs_client(config: RagfsBindingConfig) -> Any:"to build and install the RAGFS SDK with native bindings.")+ agfs_config = config.agfs if isinstance(config, RagfsBindingConfig) else config+ binding_dict = config.to_binding_dict()+ if git_config is not None and getattr(git_config, "enabled", False):+ path_str = getattr(agfs_config, "path", None)+ if path_str is None:+ raise ValueError("agfs_config.path is required when git is enabled")+ storage_path = Path(path_str).resolve()+ binding_dict["git"] = _build_git_config_dict(git_config, storage_path)+# Construction-time decides whether the stack includes the encryption layer.config_path = resolve_config_path(None, OPENVIKING_CONFIG_ENV, DEFAULT_OV_CONF)client = RAGFSBindingClient(str(config_path) if config_path else None,- config=config.to_binding_dict(),+ config=binding_dict,)# Automatically mount backend for binding clientdiff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.pyindex 7b844cb5c..d68baa77b 100644--- a/openviking_cli/client/base.py+++ b/openviking_cli/client/base.py@@ -469,3 +469,49 @@ class BaseClient(ABC):def observer(self) -> Any:"""Get observer service for component status."""...++ # ============= Git Version Control =============++ @abstractmethod+ async def git_commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Create a git snapshot. See VikingFS.commit for semantics."""++ @abstractmethod+ async def git_restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Restore a subtree, or the full account tree when project_dir is omitted."""++ @abstractmethod+ async def git_show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ """Read a commit's metadata or a single blob."""++ @abstractmethod+ async def git_log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ """Walk back along parents[0] up to limit commits."""diff --git a/openviking_cli/utils/config/__init__.py b/openviking_cli/utils/config/__init__.pyindex 31ea7202c..60dd31315 100644--- a/openviking_cli/utils/config/__init__.py+++ b/openviking_cli/utils/config/__init__.py@@ -52,6 +52,7 @@ from .consts import ()from .embedding_config import EmbeddingConfigfrom .grep_config import GrepConfig, GrepEngine+from .git_config import GitConfig, GitLocalConfig, GitS3Configfrom .log_config import LogConfigfrom .open_viking_config import (OpenVikingConfig,@@ -161,4 +162,7 @@ __all__ = ["is_valid_openviking_config","TelemetryConfig","TracerConfig",+ "GitConfig",+ "GitLocalConfig",+ "GitS3Config",]diff --git a/openviking_cli/utils/config/git_config.py b/openviking_cli/utils/config/git_config.pynew file mode 100644index 000000000..000962d37--- /dev/null+++ b/openviking_cli/utils/config/git_config.py@@ -0,0 +1,121 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Git version control configuration for OpenViking."""+from typing import Literal, Optional++from pydantic import BaseModel, Field, model_validator+++class GitLocalConfig(BaseModel):+ """Configuration for the local git object backend."""++ base_dir: str = Field(+ default="",+ description="Filesystem directory holding git objects/refs. "+ "When empty, defaults to '{storage.path}/.ovgit'.",+ )++ model_config = {"extra": "forbid"}+++class GitS3Config(BaseModel):+ """Configuration for the S3 git object/ref backend.++ Fields mirror the Rust ``GitS3ConfigPy`` serde struct so that the rendered+ ``[git.s3]`` TOML section is consumed verbatim by the ragfs binding.+ """++ bucket: str = Field(+ default="",+ description="S3 bucket name holding git objects/refs.",+ )+ region: str = Field(+ default="us-east-1",+ description="AWS region where the bucket is located (e.g., us-east-1, cn-beijing).",+ )+ prefix: str = Field(+ default=".ovgit",+ description="Key prefix for git storage. All keys are stored under '{prefix}/{account}/...'.",+ )+ endpoint: str = Field(+ default="",+ description="Custom S3 endpoint URL for S3-compatible services like MinIO/LocalStack/TOS. "+ "Leave empty for standard AWS S3.",+ )+ access_key: Optional[str] = Field(+ default=None,+ description="S3 access key ID read directly from config. "+ "When empty, the SDK default credentials chain is used.",+ )+ secret_key: Optional[str] = Field(+ default=None,+ description="S3 secret access key read directly from config. "+ "When empty, the SDK default credentials chain is used.",+ )+ cas_mode: Literal["native"] = Field(+ default="native",+ description="Ref CAS mode. 'native' uses S3 conditional writes (If-Match). "+ "It is the only supported mode.",+ )+ use_path_style: bool = Field(+ default=True,+ description="true uses path-style addressing (MinIO and some S3-compatible services); "+ "false uses virtual-host style (TOS and some S3-compatible services).",+ )++ model_config = {"extra": "forbid"}+++class GitConfig(BaseModel):+ """Git multi-version management configuration."""++ enabled: bool = Field(+ default=True,+ description="Enable git-based multi-version management for VikingFS content.",+ )+ backend: Literal["local", "s3"] = Field(+ default="local",+ description="Git object backend. 'local' stores objects on the local filesystem; "+ "'s3' stores them on a remote S3-compatible bucket. When unset, defaults to "+ "the same backend as 'storage.agfs.backend' (a 'memory' storage backend maps "+ "to 'local').",+ )+ default_branch: str = Field(+ default="main",+ description="Default branch name for commits when not specified.",+ )+ author_name: str = Field(+ default="viking-bot",+ description="Default author name used when callers omit author_name.",+ )+ author_email: str = Field(+ default="[email protected]",+ description="Default author email used when callers omit author_email.",+ )+ local: GitLocalConfig = Field(+ default_factory=GitLocalConfig,+ description="Configuration for the 'local' backend.",+ )+ s3: Optional[GitS3Config] = Field(+ default=None,+ description="Configuration for the 's3' backend. Required when backend='s3'.",+ )++ model_config = {"extra": "forbid"}++ @model_validator(mode="after")+ def _validate_backend(self) -> "GitConfig":+ """Ensure the selected backend has the required configuration."""+ if self.enabled and self.backend == "s3":+ if self.s3 is None:+ raise ValueError("git backend 's3' requires a [git.s3] section")+ missing = []+ if not self.s3.bucket:+ missing.append("bucket")+ if not self.s3.region:+ missing.append("region")+ if missing:+ raise ValueError(+ f"git backend 's3' requires the following fields: {', '.join(missing)}"+ )+ return selfdiff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.pyindex de72d1421..85e191c6f 100644--- a/openviking_cli/utils/config/open_viking_config.py+++ b/openviking_cli/utils/config/open_viking_config.py@@ -22,6 +22,7 @@ from .consts import (from .embedding_config import EmbeddingConfigfrom .encryption_config import EncryptionConfigfrom .grep_config import GrepConfig+from .git_config import GitConfigfrom .log_config import LogConfigfrom .memory_config import MemoryConfigfrom .oauth_config import OAuthConfig@@ -146,6 +147,10 @@ class OpenVikingConfig(BaseModel):default_factory=EncryptionConfig, description="Encryption configuration")+ git: GitConfig = Field(+ default_factory=GitConfig, description="Git version control configuration"+ )+# Parser configurationspdf: PDFConfig = Field(default_factory=PDFConfig, description="PDF parsing configuration")@@ -233,6 +238,58 @@ class OpenVikingConfig(BaseModel):)return self+ @model_validator(mode="before")+ @classmethod+ def _inherit_git_defaults_from_agfs(cls, data: Any) -> Any:+ """Let the `git` section inherit unset defaults from `storage.agfs`.++ - `git.backend` defaults to `storage.agfs.backend` (a 'memory' storage+ backend maps to 'local') when not set explicitly.+ - When the effective git backend is 's3', the `git.s3` fields+ bucket/region/endpoint/access_key/secret_key default to the matching+ `storage.agfs.s3` values when not set explicitly and the source value+ is non-empty.++ Injecting into the raw dict keeps GitConfig's own validation intact.+ """+ if not isinstance(data, dict):+ return data++ storage = data.get("storage")+ agfs = storage.get("agfs", {}) if isinstance(storage, dict) else {}+ if not isinstance(agfs, dict):+ agfs = {}++ git = data.get("git")+ if not isinstance(git, dict):+ if git is not None:+ # git provided as a model instance; respect it as-is.+ return data+ git = {}+ git = dict(git)++ if "backend" not in git:+ agfs_backend = agfs.get("backend", "local")+ if agfs_backend == "memory":+ agfs_backend = "local"+ if agfs_backend in ("local", "s3"):+ git["backend"] = agfs_backend++ if git.get("backend", "local") == "s3":+ agfs_s3 = agfs.get("s3", {})+ if not isinstance(agfs_s3, dict):+ agfs_s3 = {}+ git_s3 = git.get("s3")+ git_s3 = dict(git_s3) if isinstance(git_s3, dict) else {}+ for field in ("bucket", "region", "endpoint", "access_key", "secret_key"):+ if field not in git_s3 and agfs_s3.get(field):+ git_s3[field] = agfs_s3[field]+ git["s3"] = git_s3++ data = dict(data)+ data["git"] = git+ return data+allow_private_networks: bool = Field(default=False,description=(diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex fa907092c..c7414e670 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -243,6 +243,7 @@ class AsyncHTTPClient:self._upload_mode = config.upload_modeself._http: Optional[httpx.AsyncClient] = Noneself._observer: Optional[_HTTPObserver] = None+ self._snapshot: Optional["AsyncHTTPSnapshotNamespace"] = Noneasync def initialize(self) -> None:headers: Dict[str, str] = {}@@ -1225,11 +1226,108 @@ class AsyncHTTPClient:self._observer = _HTTPObserver(self)return self._observer+ # ============= Git Version Control =============++ async def git_commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Create a snapshot of the current workspace state."""+ body: Dict[str, Any] = {"message": message, "branch": branch}+ if paths is not None:+ body["paths"] = paths+ if author_name is not None:+ body["author_name"] = author_name+ if author_email is not None:+ body["author_email"] = author_email+ response = await self._http.post("/api/v1/snapshot/commit", json=body)+ return self._handle_response(response)++ async def git_restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ """Forward-commit restore of a subtree, or the full account tree when project_dir is omitted."""+ body: Dict[str, Any] = {+ "source_commit": source_commit,+ "branch": branch,+ "dry_run": dry_run,+ }+ if project_dir is not None:+ body["project_dir"] = project_dir+ if message is not None:+ body["message"] = message+ if author_name is not None:+ body["author_name"] = author_name+ if author_email is not None:+ body["author_email"] = author_email+ response = await self._http.post("/api/v1/snapshot/restore", json=body)+ return self._handle_response(response)++ async def git_show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ """Fetch commit metadata (path=None) or a blob's {oid, size, bytes} (path=<uri>)."""+ params: Dict[str, Any] = {"target_ref": target_ref}+ if path is not None:+ params["path"] = path+ response = await self._http.get("/api/v1/snapshot/show", params=params)++ if path is None:+ return self._handle_response(response)++ # Binary branch: server sets application/octet-stream + X-Snapshot-* headers.+ content_type = response.headers.get("content-type", "")+ if content_type.startswith("application/octet-stream"):+ return {+ "oid": response.headers.get("x-snapshot-oid", ""),+ "size": int(response.headers.get("x-snapshot-size", "0")),+ "bytes": response.content,+ }+ # Fallback: server returned a JSON error envelope. Let the standard handler raise.+ return self._handle_response(response)++ async def git_log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ """Walk commit history newest-first."""+ response = await self._http.get(+ "/api/v1/snapshot/log",+ params={"branch": branch, "limit": limit},+ )+ return self._handle_response(response)++ @property+ def snapshot(self) -> "AsyncHTTPSnapshotNamespace":+ """Snapshot version control namespace (async HTTP)."""+ if self._snapshot is None:+ self._snapshot = AsyncHTTPSnapshotNamespace(self)+ return self._snapshot+class SyncHTTPClient:def __init__(self, *args, **kwargs):self._async_client = AsyncHTTPClient(*args, **kwargs)self._initialized = False+ self._snapshot: Optional["SyncHTTPSnapshotNamespace"] = Nonedef initialize(self) -> None:run_async(self._async_client.initialize())@@ -1823,6 +1921,13 @@ class SyncHTTPClient:def observer(self) -> _HTTPObserver:return self._async_client.observer+ @property+ def snapshot(self) -> "SyncHTTPSnapshotNamespace":+ """Snapshot version control namespace (sync HTTP)."""+ if self._snapshot is None:+ self._snapshot = SyncHTTPSnapshotNamespace(self)+ return self._snapshot+def __getattr__(self, name: str):attr = getattr(self._async_client, name)if inspect.iscoroutinefunction(attr):@@ -1832,3 +1937,132 @@ class SyncHTTPClient:return wrapperreturn attr+++class AsyncHTTPSnapshotNamespace:+ """Snapshot version control namespace forwarding to AsyncHTTPClient git_* methods."""++ def __init__(self, client: "AsyncHTTPClient"):+ self._client = client++ async def commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return await self._client.git_commit(+ message=message,+ paths=paths,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ )++ async def restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return await self._client.git_restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ )++ async def show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ return await self._client.git_show(target_ref, path=path)++ async def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ return await self._client.git_log(branch=branch, limit=limit)+++class SyncHTTPSnapshotNamespace:+ """Synchronous wrapper around the HTTP client's snapshot namespace."""++ def __init__(self, client: "SyncHTTPClient"):+ self._client = client++ def _ns(self) -> AsyncHTTPSnapshotNamespace:+ return self._client._async_client.snapshot++ def commit(+ self,+ *,+ message: str,+ paths: Optional[List[str]] = None,+ branch: str = "main",+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return run_async(+ self._ns().commit(+ message=message,+ paths=paths,+ branch=branch,+ author_name=author_name,+ author_email=author_email,+ )+ )++ def restore(+ self,+ *,+ project_dir: Optional[str] = None,+ source_commit: str,+ branch: str = "main",+ dry_run: bool = False,+ message: Optional[str] = None,+ author_name: Optional[str] = None,+ author_email: Optional[str] = None,+ ) -> Dict[str, Any]:+ return run_async(+ self._ns().restore(+ project_dir=project_dir,+ source_commit=source_commit,+ branch=branch,+ dry_run=dry_run,+ message=message,+ author_name=author_name,+ author_email=author_email,+ )+ )++ def show(+ self,+ target_ref: str,+ *,+ path: Optional[str] = None,+ ) -> Any:+ return run_async(self._ns().show(target_ref, path=path))++ def log(+ self,+ *,+ branch: str = "main",+ limit: int = 20,+ ) -> List[Dict[str, Any]]:+ return run_async(self._ns().log(branch=branch, limit=limit))diff --git a/tests/agfs/test_git_binding.py b/tests/agfs/test_git_binding.pynew file mode 100644index 000000000..47bbcedac--- /dev/null+++ b/tests/agfs/test_git_binding.py@@ -0,0 +1,316 @@+"""End-to-end tests for the git_commit/git_restore/git_show PyO3 bindings.++These tests exercise the binding through ragfs_python.RAGFSBindingClient+directly so they don't require the higher-level VikingFS layer.+"""++import shutil+import tempfile+from pathlib import Path++import pytest+++# Skip the whole module if the native extension is not built locally.+ragfs_python = pytest.importorskip("ragfs_python")+++# ---------------- fixtures ----------------+++def git_workspace():+ """Create a temp workspace containing a localfs root and a [git] config TOML.++ Yields (config_path, localfs_root, git_root) and removes the dir on exit.+ """+ root = Path(tempfile.mkdtemp(prefix="ov-git-binding-"))+ localfs_root = root / "fs"+ git_root = root / "git"+ localfs_root.mkdir()+ git_root.mkdir()++ config_path = root / "ragfs.toml"+ config_path.write_text(+ f"""+[git]+enabled = true+backend = "local"+default_branch = "main"+author_name = "test-bot"+author_email = "[email protected]"++[git.local]+base_dir = "{git_root}"+"""+ )++ yield config_path, localfs_root, git_root++ shutil.rmtree(root, ignore_errors=True)+++def git_disabled_workspace():+ """A workspace whose [git] section has enabled = false."""+ root = Path(tempfile.mkdtemp(prefix="ov-git-disabled-"))+ config_path = root / "ragfs.toml"+ config_path.write_text(+ """+[git]+enabled = false+"""+ )+ yield config_path+ shutil.rmtree(root, ignore_errors=True)+++def client(git_workspace):+ config_path, localfs_root, _ = git_workspace+ c = ragfs_python.RAGFSBindingClient(git_config_path=str(config_path))+ # Mount localfs at /local so we can write files into the account tree.+ c.mount("localfs", "/local", {"local_dir": str(localfs_root)})+ return c+++# ---------------- helper: write a file into account tree ----------------+++def _write(client, account: str, rel_path: str, body: bytes) -> str:+ """Write `body` to /local/<account>/<rel_path> via the binding."""+ path = f"/local/{account}/{rel_path}"+ client.ensure_parent_dirs(path)+ client.write(path, body)+ return path+++# ---------------- tests ----------------+++def test_git_concurrent_commit_error_class_exists():+ from openviking.pyagfs import GitConcurrentCommitError+ from openviking.pyagfs.exceptions import AGFSClientError+ assert issubclass(GitConcurrentCommitError, AGFSClientError)+++def test_health_reports_git_enabled(client):+ h = client.health()+ assert h["git_enabled"] == "true"+ assert h.get("git_backend") == "local"+++def test_commit_then_show_roundtrip(client):+ """Write a file, commit it, then show it back and verify bytes match."""+ account = "acct1"+ _write(client, account, "resources/a.md", b"hello world")++ resp = client.git_commit(+ account=account,+ branch="main",+ message="initial",+ author_name="alice",+ author_email="[email protected]",+ paths=["resources/a.md"],+ )+ assert resp["result"] == "created"+ assert resp["changed"] == 1+ commit_oid = resp["commit_oid"]+ assert len(commit_oid) == 40++ shown = client.git_show(+ account=account,+ target_ref="main",+ path="resources/a.md",+ )+ assert shown["bytes"] == b"hello world"+ assert shown["size"] == 11+++def test_commit_then_show_commit_metadata(client):+ account = "acct1"+ _write(client, account, "resources/a.md", b"x")+ resp = client.git_commit(+ account=account,+ branch="main",+ message="m1",+ author_name="alice",+ author_email="[email protected]",+ paths=["resources/a.md"],+ )+ meta = client.git_show(account=account, target_ref="main")+ assert meta["message"].startswith("m1")+ assert meta["oid"] == resp["commit_oid"]+ assert meta["parents"] == []+ assert meta["author"]["name"] == "alice"+++def test_restore_roundtrip(client):+ """Commit v1 → modify → commit v2 → restore v1 → file reverts; HEAD moves to v3."""+ account = "acct1"+ _write(client, account, "resources/proj/a.md", b"v1-content")++ v1 = client.git_commit(+ account=account, branch="main", message="v1",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )+ v1_oid = v1["commit_oid"]++ _write(client, account, "resources/proj/a.md", b"v2-content")+ v2 = client.git_commit(+ account=account, branch="main", message="v2",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )+ v2_oid = v2["commit_oid"]++ restored = client.git_restore(+ account=account, branch="main",+ project_dir="resources/proj",+ source_commit=v1_oid,+ author_name="a", author_email="a@e",+ )+ assert restored["result"] == "applied"+ assert restored["source_commit"] == v1_oid+ assert restored["parent_commit"] == v2_oid+ assert restored["new_commit_oid"] != v2_oid+ assert restored["written"] >= 1++ # VFS file content reverted+ content = client.read(f"/local/{account}/resources/proj/a.md")+ assert content == b"v1-content"++ # Branch now points at the new commit+ head = client.git_show(account=account, target_ref="main")+ assert head["oid"] == restored["new_commit_oid"]+ assert head["parents"] == [v2_oid]+++def test_restore_dry_run_does_not_mutate(client):+ account = "acct1"+ _write(client, account, "resources/proj/a.md", b"v1")+ v1 = client.git_commit(+ account=account, branch="main", message="v1",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )++ _write(client, account, "resources/proj/a.md", b"v2")+ client.git_commit(+ account=account, branch="main", message="v2",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )++ res = client.git_restore(+ account=account, branch="main",+ project_dir="resources/proj",+ source_commit=v1["commit_oid"],+ author_name="a", author_email="a@e",+ dry_run=True,+ )+ assert res["result"] == "dry_run"+ assert "diff" in res+ assert any(item["path"] == "a.md" for item in res["diff"]["to_write"])++ # VFS still holds v2 — dry_run did not write+ assert client.read(f"/local/{account}/resources/proj/a.md") == b"v2"+++def test_account_isolation(client):+ """A commit under account A is invisible to account B."""+ _write(client, "acct_a", "resources/a.md", b"x")+ client.git_commit(+ account="acct_a", branch="main", message="m",+ author_name="n", author_email="e",+ paths=["resources/a.md"],+ )++ from openviking.pyagfs import AGFSNotFoundError+ with pytest.raises(AGFSNotFoundError):+ client.git_show(account="acct_b", target_ref="main")+++def test_feature_disabled_raises(git_disabled_workspace):+ from openviking.pyagfs import AGFSNotSupportedError+ c = ragfs_python.RAGFSBindingClient(git_config_path=str(git_disabled_workspace))+ with pytest.raises(AGFSNotSupportedError):+ c.git_commit(+ account="a", branch="main", message="m",+ author_name="n", author_email="e",+ )+++def test_invalid_backend_at_construct_time(tmp_path):+ cfg = tmp_path / "bad.toml"+ cfg.write_text(+ """+[git]+enabled = true+backend = "bogus"+"""+ )+ with pytest.raises(Exception) as excinfo:+ ragfs_python.RAGFSBindingClient(git_config_path=str(cfg))+ assert "unsupported git backend" in str(excinfo.value).lower()+++def test_cas_conflict_surface(client):+ """Two commits trying to advance from the same parent — one should win,+ the other should raise GitConcurrentCommitError.++ We provoke this by writing two different files, then issuing two+ git_commit calls back-to-back with paths overlapping enough that both+ actually produce new tree objects.+ """+ import threading++ from openviking.pyagfs import GitConcurrentCommitError++ account = "acct_cas"+ _write(client, account, "resources/seed.md", b"seed")+ client.git_commit(+ account=account, branch="main", message="seed",+ author_name="n", author_email="e",+ paths=["resources/seed.md"],+ )++ # Prepare two divergent changes+ _write(client, account, "resources/a.md", b"AAA")+ _write(client, account, "resources/b.md", b"BBB")++ errors: list[BaseException] = []+ results: list[dict] = []+ barrier = threading.Barrier(2)++ def do_commit(path: str):+ try:+ barrier.wait()+ r = client.git_commit(+ account=account, branch="main", message=f"commit {path}",+ author_name="n", author_email="e",+ paths=[path],+ )+ results.append(r)+ except BaseException as e:+ errors.append(e)++ t1 = threading.Thread(target=do_commit, args=("resources/a.md",))+ t2 = threading.Thread(target=do_commit, args=("resources/b.md",))+ t1.start(); t2.start()+ t1.join(); t2.join()++ # The LocalRefStore mutex + CAS may serialize the two so well that the+ # second sees the new parent and the conflict never surfaces. In that case+ # both succeed and form a linear history — that is also correct behavior.+ # We accept either outcome but verify that NO silent data loss occurs:+ # if both succeed, the second's commit_oid != the first's; if one fails,+ # the failure must be GitConcurrentCommitError.+ if len(errors) == 1:+ assert isinstance(errors[0], GitConcurrentCommitError), errors[0]+ assert len(results) == 1+ else:+ assert errors == [], errors+ assert len(results) == 2+ assert results[0]["commit_oid"] != results[1]["commit_oid"]diff --git a/tests/agfs/test_git_binding_s3.py b/tests/agfs/test_git_binding_s3.pynew file mode 100644index 000000000..d0a96926e--- /dev/null+++ b/tests/agfs/test_git_binding_s3.py@@ -0,0 +1,337 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""End-to-end tests for the git_commit/git_restore/git_show PyO3 bindings on+the **S3/TOS** backend (audit plan §A4).++These mirror the local-backend flow in ``test_git_binding.py`` but wire the+binding to a real S3-compatible store (TOS / MinIO / LocalStack):++* git objects/refs go to ``[git.s3]`` (namespaced under ``{prefix}/_it/{uuid}``)+* the working tree is an ``s3fs`` mount at ``/local`` (namespaced under a+ separate ``_it_fs/{uuid}`` prefix)++so concurrent runs never collide and never touch real data.++Skip gating mirrors ``test_fs_binding_s3.py``: the whole module is skipped+unless a config file with ``git.enabled = true`` and ``git.backend = "s3"`` is+discoverable. Resolution order (first hit wins):++ 1. ``OV_GIT_S3_CONF`` env var (explicit path to an ``ov.conf`` JSON file)+ 2. ``OPENVIKING_CONFIG_FILE`` env var++Run against TOS::++ OV_GIT_S3_CONF=/path/to/ov.conf \+ python -m pytest tests/agfs/test_git_binding_s3.py -q+"""++import json+import os+import shutil+import tempfile+import uuid+from pathlib import Path++import pytest++# Skip the whole module if the native extension is not built locally.+ragfs_python = pytest.importorskip("ragfs_python")+++# ---------------- config discovery / skip gating ----------------+++def _resolve_conf_path():+ """Resolve an ov.conf path from the documented env-var chain."""+ for candidate in (+ os.getenv("OV_GIT_S3_CONF"),+ os.getenv("OPENVIKING_CONFIG_FILE"),+ ):+ if candidate and Path(candidate).exists():+ return Path(candidate)+ return None+++def _load_git_s3_section():+ """Return the ``git`` dict from the resolved ov.conf when it is a usable+ S3 git config, else ``None`` (treated as "skip").+ """+ path = _resolve_conf_path()+ if path is None:+ return None+ try:+ with open(path, "r") as f:+ root = json.load(f)+ except Exception:+ return None++ git = root.get("git") or root.get("storage", {}).get("git")+ if not git:+ return None+ if not git.get("enabled"):+ return None+ if git.get("backend") != "s3":+ return None+ s3 = git.get("s3") or {}+ if not s3.get("bucket") or not s3.get("region"):+ return None+ return git+++GIT_S3 = _load_git_s3_section()++pytestmark = pytest.mark.skipif(+ GIT_S3 is None,+ reason="no usable [git.s3] config (set OV_GIT_S3_CONF to an ov.conf with "+ "git.enabled=true, backend='s3')",+)+++# ---------------- fixtures ----------------+++def _toml_quote(s: str) -> str:+ return '"' + str(s).replace("\\", "\\\\").replace('"', '\\"') + '"'+++def _toml_bool(v) -> str:+ return "true" if v else "false"+++def git_s3_workspace():+ """Create a temp workspace with a ragfs.toml whose [git] backend is s3.++ The git object/ref keys are namespaced under ``{prefix}/_it/{uuid}`` so+ repeated runs never collide. Yields ``(config_path, fs_prefix, s3)`` where+ ``s3`` is the raw s3 config dict and ``fs_prefix`` is a unique prefix to+ use for the s3fs working-tree mount.+ """+ s3 = GIT_S3["s3"]+ run_id = uuid.uuid4().hex+ base_prefix = (s3.get("prefix") or "git").rstrip("/")+ git_prefix = f"{base_prefix}/_it/{run_id}"+ fs_prefix = f"{base_prefix}/_it_fs/{run_id}"++ root = Path(tempfile.mkdtemp(prefix="ov-git-s3-binding-"))+ config_path = root / "ragfs.toml"++ lines = [+ "[git]\n",+ "enabled = true\n",+ 'backend = "s3"\n',+ 'default_branch = "main"\n',+ 'author_name = "test-bot"\n',+ 'author_email = "[email protected]"\n',+ "\n",+ "[git.s3]\n",+ f"bucket = {_toml_quote(s3['bucket'])}\n",+ f"region = {_toml_quote(s3['region'])}\n",+ f"prefix = {_toml_quote(git_prefix)}\n",+ f"endpoint = {_toml_quote(s3.get('endpoint', ''))}\n",+ ]+ if s3.get("access_key"):+ lines.append(f"access_key = {_toml_quote(s3['access_key'])}\n")+ if s3.get("secret_key"):+ lines.append(f"secret_key = {_toml_quote(s3['secret_key'])}\n")+ lines.append(f"cas_mode = {_toml_quote(s3.get('cas_mode', 'native'))}\n")+ lines.append(f"use_path_style = {_toml_bool(s3.get('use_path_style', True))}\n")+ config_path.write_text("".join(lines))++ yield config_path, fs_prefix, s3++ shutil.rmtree(root, ignore_errors=True)+++def client(git_s3_workspace):+ config_path, fs_prefix, s3 = git_s3_workspace+ c = ragfs_python.RAGFSBindingClient(git_config_path=str(config_path))+ # Mount s3fs at /local so the working tree lives on the same S3 backend.+ mount_cfg = {+ "bucket": s3["bucket"],+ "region": s3["region"],+ "endpoint": s3.get("endpoint", ""),+ "prefix": fs_prefix,+ "use_path_style": bool(s3.get("use_path_style", True)),+ "disable_ssl": not bool(s3.get("use_ssl", True)),+ }+ if s3.get("access_key"):+ mount_cfg["access_key_id"] = s3["access_key"]+ if s3.get("secret_key"):+ mount_cfg["secret_access_key"] = s3["secret_key"]+ c.mount("s3fs", "/local", mount_cfg)+ return c+++# ---------------- helpers ----------------+++def _write(client, account: str, rel_path: str, body: bytes) -> str:+ """Write `body` to /local/<account>/<rel_path> via the binding."""+ path = f"/local/{account}/{rel_path}"+ client.ensure_parent_dirs(path)+ client.write(path, body)+ return path+++def _acct() -> str:+ """Random account id so concurrent runs never share a namespace."""+ return f"acct-{uuid.uuid4().hex}"+++# ---------------- tests ----------------+++def test_health_reports_git_backend_s3(client):+ h = client.health()+ assert h["git_enabled"] == "true"+ assert h.get("git_backend") == "s3"+++def test_commit_then_show_roundtrip_s3(client):+ """Write a file, commit it, then show it back and verify bytes match."""+ account = _acct()+ body = b"hello viking s3 \x00\x01\x02 binary-ish\n"+ _write(client, account, "resources/a.md", body)++ resp = client.git_commit(+ account=account,+ branch="main",+ message="initial",+ author_name="alice",+ author_email="[email protected]",+ paths=["resources/a.md"],+ )+ assert resp["result"] == "created"+ assert resp["changed"] == 1+ assert len(resp["commit_oid"]) == 40++ shown = client.git_show(+ account=account,+ target_ref="main",+ path="resources/a.md",+ )+ assert shown["bytes"] == body+ assert shown["size"] == len(body)+++def test_restore_roundtrip_s3(client):+ """Commit v1 → modify → commit v2 → restore v1 → file reverts; HEAD moves to v3."""+ account = _acct()+ _write(client, account, "resources/proj/a.md", b"v1-content")+ v1 = client.git_commit(+ account=account, branch="main", message="v1",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )+ v1_oid = v1["commit_oid"]++ _write(client, account, "resources/proj/a.md", b"v2-content")+ v2 = client.git_commit(+ account=account, branch="main", message="v2",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )+ v2_oid = v2["commit_oid"]++ restored = client.git_restore(+ account=account, branch="main",+ project_dir="resources/proj",+ source_commit=v1_oid,+ author_name="a", author_email="a@e",+ )+ assert restored["result"] == "applied"+ assert restored["source_commit"] == v1_oid+ assert restored["parent_commit"] == v2_oid+ assert restored["new_commit_oid"] != v2_oid+ assert restored["written"] >= 1++ # VFS file content reverted on S3.+ assert client.read(f"/local/{account}/resources/proj/a.md") == b"v1-content"++ # Branch now points at the new (forward-only) commit, parented on v2.+ head = client.git_show(account=account, target_ref="main")+ assert head["oid"] == restored["new_commit_oid"]+ assert head["parents"] == [v2_oid]+++def test_commit_noop_when_unchanged_s3(client):+ """A second commit with no working-tree change is a Noop on the same HEAD."""+ account = _acct()+ _write(client, account, "resources/a.md", b"stable")+ first = client.git_commit(+ account=account, branch="main", message="first",+ author_name="a", author_email="a@e",+ paths=["resources/a.md"],+ )+ assert first["result"] == "created"++ second = client.git_commit(+ account=account, branch="main", message="second",+ author_name="a", author_email="a@e",+ paths=["resources/a.md"],+ )+ assert second["result"] == "noop"+ assert second["commit_oid"] == first["commit_oid"]+++def test_cross_scope_atomic_snapshot_s3(client):+ """A single commit captures files spanning multiple scopes atomically+ (design §15.2): both resources/ and knowledge/ land in one commit tree.+ """+ account = _acct()+ _write(client, account, "resources/doc.md", b"resource body")+ _write(client, account, "knowledge/note.md", b"knowledge body")++ resp = client.git_commit(+ account=account, branch="main", message="snapshot both scopes",+ author_name="a", author_email="a@e",+ paths=["resources/doc.md", "knowledge/note.md"],+ )+ assert resp["result"] == "created"++ assert client.git_show(+ account=account, target_ref="main", path="resources/doc.md"+ )["bytes"] == b"resource body"+ assert client.git_show(+ account=account, target_ref="main", path="knowledge/note.md"+ )["bytes"] == b"knowledge body"+++def test_derived_file_rolls_back_with_restore_s3(client):+ """Derived files (e.g. .abstract.md) created after the source commit are+ removed when restoring to that earlier commit (design §15.2).+ """+ account = _acct()+ _write(client, account, "resources/proj/a.md", b"A v1")+ src = client.git_commit(+ account=account, branch="main", message="source",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md"],+ )++ # HEAD adds a derived file alongside an edit.+ _write(client, account, "resources/proj/a.md", b"A v2")+ _write(client, account, "resources/proj/.abstract.md", b"derived summary")+ client.git_commit(+ account=account, branch="main", message="head",+ author_name="a", author_email="a@e",+ paths=["resources/proj/a.md", "resources/proj/.abstract.md"],+ )++ restored = client.git_restore(+ account=account, branch="main",+ project_dir="resources/proj",+ source_commit=src["commit_oid"],+ author_name="a", author_email="a@e",+ )+ assert restored["result"] == "applied"+ assert restored["deleted"] >= 1++ # a.md rolled back, derived file gone from the working tree.+ assert client.read(f"/local/{account}/resources/proj/a.md") == b"A v1"+ from openviking.pyagfs import AGFSNotFoundError+ with pytest.raises(AGFSNotFoundError):+ client.read(f"/local/{account}/resources/proj/.abstract.md")diff --git a/tests/agfs/test_viking_fs_git.py b/tests/agfs/test_viking_fs_git.pynew file mode 100644index 000000000..7b4167eef--- /dev/null+++ b/tests/agfs/test_viking_fs_git.py@@ -0,0 +1,955 @@+"""End-to-end tests for VikingFS git commit/restore/show/log Python layer.++These exercise the full path: VikingFS.commit -> AsyncAGFSClient -> Rust+RAGFSBindingClient -> GitService, plus URI<->tree-path conversion and the+double-encryption invariant called out in the design doc.+"""++from __future__ import annotations++import asyncio+import os+import secrets+import tempfile+import shutil+from pathlib import Path+from typing import Tuple++import pytest+++ragfs_python = pytest.importorskip("ragfs_python")++from openviking.pyagfs.exceptions import (+ AGFSNotFoundError,+ AGFSNotSupportedError,+)+from openviking.server.identity import RequestContext, Role+from openviking.storage.viking_fs import VikingFS+from openviking_cli.session.user_id import UserIdentifier+++# ----------------------------- helpers -----------------------------+++def _make_ctx(account: str = "acct_t", user: str = "user1") -> RequestContext:+ return RequestContext(user=UserIdentifier(account, user), role=Role.ROOT)+++def _write_workspace(tmp_root: Path) -> Tuple[Path, Path]:+ """Lay out an fs/ dir for localfs and a git/ dir for git objects; return+ (config_path, localfs_root)."""+ fs_root = tmp_root / "fs"+ git_root = tmp_root / "git"+ fs_root.mkdir(parents=True, exist_ok=True)+ git_root.mkdir(parents=True, exist_ok=True)+ cfg = tmp_root / "ragfs.toml"+ cfg.write_text(+ f"""+[git]+enabled = true+backend = "local"+default_branch = "main"+author_name = "test-bot"+author_email = "[email protected]"++[git.local]+base_dir = "{git_root}"+"""+ )+ return cfg, fs_root+++def _build_client(config_path: Path, fs_root: Path):+ c = ragfs_python.RAGFSBindingClient(git_config_path=str(config_path))+ c.mount("localfs", "/local", {"local_dir": str(fs_root)})+ return c+++# ----------------------------- fixtures -----------------------------+++def workspace():+ root = Path(tempfile.mkdtemp(prefix="ov-vfs-git-"))+ try:+ yield root+ finally:+ shutil.rmtree(root, ignore_errors=True)+++def vfs(workspace):+ from openviking.storage.transaction import init_lock_manager, reset_lock_manager++ cfg, fs_root = _write_workspace(workspace)+ client = _build_client(cfg, fs_root)+ init_lock_manager(client)+ try:+ yield VikingFS(agfs=client)+ finally:+ reset_lock_manager()+++def vfs_disabled(workspace):+ from openviking.storage.transaction import init_lock_manager, reset_lock_manager++ cfg = workspace / "ragfs.toml"+ cfg.write_text(+ """+[git]+enabled = false+"""+ )+ fs_root = workspace / "fs"+ fs_root.mkdir()+ client = ragfs_python.RAGFSBindingClient(git_config_path=str(cfg))+ client.mount("localfs", "/local", {"local_dir": str(fs_root)})+ init_lock_manager(client)+ try:+ yield VikingFS(agfs=client)+ finally:+ reset_lock_manager()+++# =========================================================================+# 1. URI <-> tree path+# =========================================================================+++class TestUriToTreePath:+ def test_resources_uri(self, vfs):+ ctx = _make_ctx()+ assert vfs._uri_to_tree_path("viking://resources/a.md", ctx=ctx) == "resources/a.md"+ assert (+ vfs._uri_to_tree_path("viking://resources/proj_a/docs/a.md", ctx=ctx)+ == "resources/proj_a/docs/a.md"+ )++ def test_session_uri(self, vfs):+ # ``session`` is a virtual scope: it canonicalizes into the owning+ # user's sessions subtree, and the git tree path mirrors that real+ # storage layout (so commit/restore target the actual stored bytes).+ ctx = _make_ctx()+ assert vfs._uri_to_tree_path("viking://session", ctx=ctx) == "user/user1/sessions"++ def test_trailing_slash_kept_as_directory(self, vfs):+ # Normalization may strip trailing slash; this is acceptable+ ctx = _make_ctx()+ out = vfs._uri_to_tree_path("viking://resources/proj_a/", ctx=ctx)+ assert out.rstrip("/") == "resources/proj_a"++ def test_internal_scope_rejected(self, vfs):+ ctx = _make_ctx()+ for uri in (+ "viking://temp/x",+ "viking://queue/y",+ "viking://upload/z",+ ):+ with pytest.raises(ValueError):+ vfs._uri_to_tree_path(uri, ctx=ctx)++ def test_root_uri_rejected(self, vfs):+ ctx = _make_ctx()+ with pytest.raises(ValueError):+ vfs._uri_to_tree_path("viking://", ctx=ctx)++ def test_tree_path_to_uri_inverse(self, vfs):+ assert vfs._tree_path_to_uri("resources/a.md") == "viking://resources/a.md"+ assert vfs._tree_path_to_uri("/resources/a.md/") == "viking://resources/a.md"++ def test_tree_path_empty_rejected(self, vfs):+ with pytest.raises(ValueError):+ vfs._tree_path_to_uri("")+++# =========================================================================+# 2. commit / show / log+# =========================================================================+++class TestCommitShowLog:+ async def test_commit_then_show_roundtrip(self, vfs):+ ctx = _make_ctx()+ await vfs.write_file("viking://resources/a.md", b"hello", ctx=ctx)+ resp = await vfs.commit(+ message="initial",+ paths=["viking://resources/a.md"],+ ctx=ctx,+ )+ assert resp["result"] == "created"+ assert resp["changed"] == 1+ assert len(resp["commit_oid"]) == 40++ # show with path -> bytes+ body = await vfs.show("main", path="viking://resources/a.md", ctx=ctx)+ assert body == b"hello"++ # show without path -> commit metadata+ meta = await vfs.show("main", ctx=ctx)+ assert meta["message"].startswith("initial")+ assert meta["oid"] == resp["commit_oid"]+ assert meta["parents"] == []+ assert meta["author"]["name"] == "viking-bot"++ async def test_commit_with_paths_none_enumerates_account(self, vfs):+ ctx = _make_ctx(account="acct_full")+ await vfs.write_file("viking://resources/a.md", b"a", ctx=ctx)+ await vfs.write_file("viking://resources/b.md", b"b", ctx=ctx)+ resp = await vfs.commit(message="all", ctx=ctx)+ assert resp["result"] == "created"+ assert resp["changed"] == 2++ async def test_log_walks_parent_chain(self, vfs):+ ctx = _make_ctx(account="acct_log")+ await vfs.write_file("viking://resources/a.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="c1", paths=["viking://resources/a.md"], ctx=ctx)+ await vfs.write_file("viking://resources/a.md", b"v2", ctx=ctx)+ c2 = await vfs.commit(message="c2", paths=["viking://resources/a.md"], ctx=ctx)+ await vfs.write_file("viking://resources/a.md", b"v3", ctx=ctx)+ c3 = await vfs.commit(message="c3", paths=["viking://resources/a.md"], ctx=ctx)++ history = await vfs.log(limit=10, ctx=ctx)+ oids = [h["oid"] for h in history]+ assert oids == [c3["commit_oid"], c2["commit_oid"], c1["commit_oid"]]++ limited = await vfs.log(limit=2, ctx=ctx)+ assert [h["oid"] for h in limited] == [c3["commit_oid"], c2["commit_oid"]]++ async def test_show_missing_branch_raises(self, vfs):+ ctx = _make_ctx(account="acct_missing")+ with pytest.raises(AGFSNotFoundError):+ await vfs.show("main", ctx=ctx)+++# =========================================================================+# 3. restore+# =========================================================================+++class TestRestore:+ async def test_restore_reverts_file_and_advances_head(self, vfs):+ ctx = _make_ctx(account="acct_r")+ await vfs.write_file("viking://resources/proj/a.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", paths=["viking://resources/proj/a.md"], ctx=ctx)++ await vfs.write_file("viking://resources/proj/a.md", b"v2", ctx=ctx)+ c2 = await vfs.commit(message="v2", paths=["viking://resources/proj/a.md"], ctx=ctx)++ result = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ assert result["source_commit"] == c1["commit_oid"]+ assert result["parent_commit"] == c2["commit_oid"]+ assert result["new_commit_oid"] != c2["commit_oid"]+ assert "resources/proj/a.md" in result["written_paths"]++ # File reverted via VFS+ body = await vfs.read("viking://resources/proj/a.md", ctx=ctx)+ assert body == b"v1"++ # HEAD moved forward (NOT back to c1)+ head = await vfs.show("main", ctx=ctx)+ assert head["oid"] == result["new_commit_oid"]+ assert head["parents"] == [c2["commit_oid"]]++ async def test_restore_dry_run_does_not_mutate(self, vfs):+ ctx = _make_ctx(account="acct_dry")+ await vfs.write_file("viking://resources/proj/a.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", paths=["viking://resources/proj/a.md"], ctx=ctx)+ await vfs.write_file("viking://resources/proj/a.md", b"v2", ctx=ctx)+ await vfs.commit(message="v2", paths=["viking://resources/proj/a.md"], ctx=ctx)++ result = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ dry_run=True,+ ctx=ctx,+ )+ assert result["result"] == "dry_run"+ assert any(item["path"] == "a.md" for item in result["diff"]["to_write"])++ body = await vfs.read("viking://resources/proj/a.md", ctx=ctx)+ assert body == b"v2"++ async def test_restore_internal_scope_rejected(self, vfs):+ ctx = _make_ctx(account="acct_inv")+ with pytest.raises(ValueError):+ await vfs.restore(+ project_dir="viking://temp/xx",+ source_commit="main",+ ctx=ctx,+ )+++# =========================================================================+# 4. Cross-scope atomicity (resources + user in one commit)+# =========================================================================+++async def test_cross_scope_atomic_commit_and_restore(vfs):+ ctx = _make_ctx(account="acct_cross")+ # Two files in distinct scopes (``user`` is a real writable scope; the+ # virtual ``session``/``agent`` scopes are not directly writable).+ await vfs.write_file("viking://resources/a.md", b"R1", ctx=ctx)+ await vfs.write_file("viking://user/notes/b.py", b"S1", ctx=ctx)+ c1 = await vfs.commit(+ message="initial",+ paths=["viking://resources/a.md", "viking://user/notes/b.py"],+ ctx=ctx,+ )+ assert c1["result"] == "created"+ assert c1["changed"] == 2++ # Both files modified+ await vfs.write_file("viking://resources/a.md", b"R2", ctx=ctx)+ await vfs.write_file("viking://user/notes/b.py", b"S2", ctx=ctx)+ await vfs.commit(+ message="v2",+ paths=["viking://resources/a.md", "viking://user/notes/b.py"],+ ctx=ctx,+ )++ # Restore only the resources scope to c1; user scope must remain at v2+ await vfs.restore(+ project_dir="viking://resources",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert await vfs.read("viking://resources/a.md", ctx=ctx) == b"R1"+ assert await vfs.read("viking://user/notes/b.py", ctx=ctx) == b"S2"++ # Restore the user scope too -> both back to c1+ await vfs.restore(+ project_dir="viking://user/notes",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert await vfs.read("viking://resources/a.md", ctx=ctx) == b"R1"+ assert await vfs.read("viking://user/notes/b.py", ctx=ctx) == b"S1"+++# =========================================================================+# 5. Derived files (.abstract.md etc.) versioned with source+# =========================================================================+++async def test_derived_files_versioned_with_source(vfs):+ ctx = _make_ctx(account="acct_derived")+ await vfs.write_file("viking://resources/x.md", b"x-body", ctx=ctx)+ await vfs.write_file("viking://resources/x.md.abstract.md", b"abstract-v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", ctx=ctx)+ assert c1["result"] == "created"+ assert c1["changed"] == 2++ # show finds both+ assert await vfs.show("main", path="viking://resources/x.md.abstract.md", ctx=ctx) == b"abstract-v1"++ # Update derived file+ await vfs.write_file("viking://resources/x.md.abstract.md", b"abstract-v2", ctx=ctx)+ await vfs.commit(message="v2", paths=["viking://resources/x.md.abstract.md"], ctx=ctx)++ # Restore to c1 -> derived file reverts too+ await vfs.restore(+ project_dir="viking://resources",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ body = await vfs.read("viking://resources/x.md.abstract.md", ctx=ctx)+ assert body == b"abstract-v1"+++# =========================================================================+# 6. Account isolation+# =========================================================================+++async def test_account_isolation_show_misses_other_account(vfs):+ ctx_a = _make_ctx(account="acct_iso_a")+ ctx_b = _make_ctx(account="acct_iso_b")+ await vfs.write_file("viking://resources/a.md", b"a", ctx=ctx_a)+ await vfs.commit(message="m", paths=["viking://resources/a.md"], ctx=ctx_a)++ with pytest.raises(AGFSNotFoundError):+ await vfs.show("main", ctx=ctx_b)+++# =========================================================================+# 7. Double-encryption end-to-end (the §3.1 invariant)+# =========================================================================+++def encryptor(workspace):+ from openviking.crypto.encryptor import FileEncryptor+ from openviking.crypto.providers import LocalFileProvider++ key_file = workspace / "master.key"+ key_file.write_text(secrets.token_bytes(32).hex())+ os.chmod(key_file, 0o600)+ provider = LocalFileProvider(key_file=str(key_file))+ return FileEncryptor(provider)+++def vfs_encrypted(workspace, encryptor):+ from openviking.storage.transaction import init_lock_manager, reset_lock_manager++ cfg, fs_root = _write_workspace(workspace)+ client = _build_client(cfg, fs_root)+ init_lock_manager(client)+ try:+ yield VikingFS(agfs=client, encryptor=encryptor)+ finally:+ reset_lock_manager()+++async def test_double_encryption_restore_preserves_plaintext(vfs_encrypted):+ """Write plaintext via encrypted VikingFS, commit (ciphertext stored in+ git), modify, restore. After restore, VikingFS.read MUST return the+ original plaintext — proving the Rust restore path bypasses the+ VikingFS encryption layer (writes ciphertext back through MountableFS,+ which then decrypts correctly on read).+ """+ ctx = _make_ctx(account="acct_enc")+ plaintext_v1 = b"top-secret-v1"+ plaintext_v2 = b"top-secret-v2"++ await vfs_encrypted.write_file("viking://resources/secret.md", plaintext_v1, ctx=ctx)+ c1 = await vfs_encrypted.commit(+ message="v1", paths=["viking://resources/secret.md"], ctx=ctx,+ )+ assert c1["result"] == "created"++ # Modify+ await vfs_encrypted.write_file("viking://resources/secret.md", plaintext_v2, ctx=ctx)+ await vfs_encrypted.commit(+ message="v2", paths=["viking://resources/secret.md"], ctx=ctx,+ )+ assert (+ await vfs_encrypted.read("viking://resources/secret.md", ctx=ctx)+ == plaintext_v2+ )++ # Restore+ result = await vfs_encrypted.restore(+ project_dir="viking://resources",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ assert "resources/secret.md" in result["written_paths"]++ # The critical assertion: read returns original plaintext, not garbled+ # double-encrypted bytes.+ restored = await vfs_encrypted.read("viking://resources/secret.md", ctx=ctx)+ assert restored == plaintext_v1+++# =========================================================================+# 8. Feature disabled+# =========================================================================+++async def test_feature_disabled_raises_not_supported(vfs_disabled):+ ctx = _make_ctx()+ with pytest.raises(AGFSNotSupportedError):+ await vfs_disabled.commit(message="m", paths=["viking://resources/a.md"], ctx=ctx)+ with pytest.raises(AGFSNotSupportedError):+ await vfs_disabled.show("main", ctx=ctx)+ with pytest.raises(AGFSNotSupportedError):+ await vfs_disabled.restore(+ project_dir="viking://resources/proj",+ source_commit="main",+ ctx=ctx,+ )+++# =========================================================================+# 9. Reindex redirect for derived files+# =========================================================================+++def test_classify_restore_path(vfs):+ from openviking.core.context import ContextLevel++ # Directory-level markers -> (op, dir_uri, level)+ assert vfs._classify_restore_path(+ "resources/proj/.abstract.md", deleted=False+ ) == ("reindex_marker", "viking://resources/proj", ContextLevel.ABSTRACT)+ assert vfs._classify_restore_path(+ "resources/proj/.overview.md", deleted=False+ ) == ("reindex_marker", "viking://resources/proj", ContextLevel.OVERVIEW)+ assert vfs._classify_restore_path(+ "resources/proj/.abstract.md", deleted=True+ ) == ("delete", "viking://resources/proj", ContextLevel.ABSTRACT)+ assert vfs._classify_restore_path(+ "resources/proj/.overview.md", deleted=True+ ) == ("delete", "viking://resources/proj", ContextLevel.OVERVIEW)++ # .relations.json has no vector side-effect+ assert vfs._classify_restore_path(+ "resources/proj/.relations.json", deleted=False+ ) is None+ assert vfs._classify_restore_path(+ "resources/proj/.relations.json", deleted=True+ ) is None++ # Per-file sidecars do NOT exist in production -> treated as ordinary source files+ assert vfs._classify_restore_path(+ "resources/proj/x.md.abstract.md", deleted=False+ ) == ("reindex_file", "viking://resources/proj/x.md.abstract.md", ContextLevel.DETAIL)+ assert vfs._classify_restore_path(+ "resources/proj/x.md.overview.md", deleted=True+ ) == ("delete", "viking://resources/proj/x.md.overview.md", ContextLevel.DETAIL)++ # Source files -> DETAIL reindex/delete+ assert vfs._classify_restore_path(+ "resources/proj/x.md", deleted=False+ ) == ("reindex_file", "viking://resources/proj/x.md", ContextLevel.DETAIL)+ assert vfs._classify_restore_path(+ "resources/proj/x.md", deleted=True+ ) == ("delete", "viking://resources/proj/x.md", ContextLevel.DETAIL)++ # Directory marker at the account root -> None (no parent dir to scope)+ assert vfs._classify_restore_path(".abstract.md", deleted=False) is None+++class _SpyExecutor:+ """Records every scheduled vector task as a normalized tuple."""++ def __init__(self):+ self.calls: list[tuple] = []++ async def execute(self, *, uri, mode, wait, ctx):+ self.calls.append(("reindex_file", uri))+ return {"ok": True}++ async def reindex_directory_marker(self, *, dir_uri, level, ctx):+ self.calls.append(("reindex_marker", dir_uri, int(level)))++ async def delete_uri_level(self, *, uri, level, ctx):+ self.calls.append(("delete", uri, int(level)))+ return 0+++async def test_restore_schedules_reindex_for_derived_only_change(vfs, monkeypatch):+ """When a restore only changes a directory `.abstract.md` (source file+ unchanged), exactly that directory's L0 vector must be recomputed via+ reindex_directory_marker — and nothing else (no whole-tree rebuild).+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_derived_only")+ await vfs.write_file("viking://resources/proj/x.md", b"body", ctx=ctx)+ await vfs.write_file(+ "viking://resources/proj/.abstract.md", b"abs-v1", ctx=ctx+ )+ c1 = await vfs.commit(message="v1", ctx=ctx)+ assert c1["result"] == "created"++ # Modify ONLY the directory marker; source file untouched+ await vfs.write_file(+ "viking://resources/proj/.abstract.md", b"abs-v2", ctx=ctx+ )+ c2 = await vfs.commit(+ message="v2",+ paths=["viking://resources/proj/.abstract.md"],+ ctx=ctx,+ )+ assert c2["result"] == "created"+ assert c2["changed"] == 1++ result = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ assert "resources/proj/.abstract.md" in result["written_paths"]++ # Let the fire-and-forget tasks run+ await asyncio.sleep(0)+ await asyncio.sleep(0)++ assert spy.calls == [("reindex_marker", "viking://resources/proj", 0)]+++async def test_restore_schedules_marker_and_files_independently(vfs, monkeypatch):+ """Ancestor subsumption is gone: a changed directory marker recomputes the+ directory's L0/L1, while each changed source file independently reindexes+ its own DETAIL vector — neither subsumes the other.+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_dedup")+ await vfs.write_file("viking://resources/proj/x.md", b"v1", ctx=ctx)+ await vfs.write_file("viking://resources/proj/y.md", b"yv1", ctx=ctx)+ await vfs.write_file(+ "viking://resources/proj/.abstract.md", b"a-v1", ctx=ctx+ )+ c1 = await vfs.commit(message="v1", ctx=ctx)++ await vfs.write_file("viking://resources/proj/x.md", b"v2", ctx=ctx)+ await vfs.write_file("viking://resources/proj/y.md", b"yv2", ctx=ctx)+ await vfs.write_file(+ "viking://resources/proj/.abstract.md", b"a-v2", ctx=ctx+ )+ await vfs.commit(message="v2", ctx=ctx)++ await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ await asyncio.sleep(0)+ await asyncio.sleep(0)++ # Directory marker recompute + each source file's DETAIL, all independent.+ assert sorted(spy.calls) == sorted([+ ("reindex_marker", "viking://resources/proj", 0),+ ("reindex_file", "viking://resources/proj/x.md"),+ ("reindex_file", "viking://resources/proj/y.md"),+ ])+++async def test_restore_schedules_siblings_independently(vfs, monkeypatch):+ """Source files in sibling directories are each scheduled independently;+ a directory marker change only affects its own directory.+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_subsume_sibling")+ # proj_a: source file + directory marker+ await vfs.write_file("viking://resources/proj_a/x.md", b"v1", ctx=ctx)+ await vfs.write_file(+ "viking://resources/proj_a/.abstract.md", b"a-v1", ctx=ctx+ )+ # proj_b: source file only — sibling directory+ await vfs.write_file("viking://resources/proj_b/y.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", ctx=ctx)++ await vfs.write_file("viking://resources/proj_a/x.md", b"v2", ctx=ctx)+ await vfs.write_file(+ "viking://resources/proj_a/.abstract.md", b"a-v2", ctx=ctx+ )+ await vfs.write_file("viking://resources/proj_b/y.md", b"v2", ctx=ctx)+ await vfs.commit(message="v2", ctx=ctx)++ # Restore the whole resources scope so proj_a + proj_b both revert+ await vfs.restore(+ project_dir="viking://resources",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ await asyncio.sleep(0)+ await asyncio.sleep(0)++ assert sorted(spy.calls) == sorted([+ ("reindex_marker", "viking://resources/proj_a", 0),+ ("reindex_file", "viking://resources/proj_a/x.md"),+ ("reindex_file", "viking://resources/proj_b/y.md"),+ ])+++async def test_restore_deletes_marker_and_source_vectors(vfs, monkeypatch):+ """Bug 1 regression: restoring to a revision that predates a whole+ directory must delete BOTH the directory's L0/L1 marker vectors and the+ deleted source file's DETAIL vector — no orphaned vectors left behind.+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_del_marker")+ await vfs.write_file("viking://resources/keep/k.md", b"keep", ctx=ctx)+ c1 = await vfs.commit(message="v1", ctx=ctx)++ # v2 adds a whole new directory with a source file + directory markers.+ await vfs.write_file("viking://resources/gone/g.md", b"gone", ctx=ctx)+ await vfs.write_file("viking://resources/gone/.abstract.md", b"abs", ctx=ctx)+ await vfs.write_file("viking://resources/gone/.overview.md", b"ovr", ctx=ctx)+ await vfs.commit(message="v2", ctx=ctx)++ # Restore back to v1: everything under gone/ must be removed.+ result = await vfs.restore(+ project_dir="viking://resources",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ await asyncio.sleep(0)+ await asyncio.sleep(0)++ assert ("delete", "viking://resources/gone", 0) in spy.calls+ assert ("delete", "viking://resources/gone", 1) in spy.calls+ assert ("delete", "viking://resources/gone/g.md", 2) in spy.calls+ # No whole-tree reindex of the deleted dir.+ assert all(c[0] != "reindex_marker" or c[1] != "viking://resources/gone" for c in spy.calls)+++async def test_restore_relations_json_has_no_vector_side_effect(vfs, monkeypatch):+ """A restore that only touches `.relations.json` must schedule no vector+ reindex/delete tasks at all.+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_relations")+ await vfs.write_file(+ "viking://resources/proj/.relations.json", b"{\"v\":1}", ctx=ctx+ )+ c1 = await vfs.commit(message="v1", ctx=ctx)++ await vfs.write_file(+ "viking://resources/proj/.relations.json", b"{\"v\":2}", ctx=ctx+ )+ c2 = await vfs.commit(+ message="v2",+ paths=["viking://resources/proj/.relations.json"],+ ctx=ctx,+ )+ assert c2["result"] == "created"++ result = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ await asyncio.sleep(0)+ await asyncio.sleep(0)++ assert spy.calls == []+ # No vector side-effect -> no tracked task.+ assert "task_id" not in result+++async def test_restore_returns_pollable_task_id(vfs, monkeypatch):+ """An applied restore with vector side-effects returns a ``task_id`` that+ can be polled via the TaskTracker and reaches ``completed``.+ """+ spy = _SpyExecutor()++ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ from openviking.service.task_tracker import (+ TaskTracker,+ reset_task_tracker,+ set_task_tracker,+ )++ class _MemTaskStore:+ async def create(self, task):+ return None++ async def update(self, task):+ return None++ async def get(self, task_id, *, account_id=None, user_id=None):+ return None++ async def list(self, account_id, *, user_id=None):+ return []++ async def delete(self, task_id, *, account_id, user_id=None):+ return None++ set_task_tracker(TaskTracker(store=_MemTaskStore()))+ try:+ ctx = _make_ctx(account="acct_taskid")+ await vfs.write_file("viking://resources/proj/x.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", ctx=ctx)+ await vfs.write_file("viking://resources/proj/x.md", b"v2", ctx=ctx)+ await vfs.commit(message="v2", ctx=ctx)++ result = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert result["result"] == "applied"+ task_id = result.get("task_id")+ assert task_id++ # Let the tracked background worker run to completion.+ for _ in range(5):+ await asyncio.sleep(0)++ from openviking.service.task_tracker import get_task_tracker++ tracker = get_task_tracker()+ task = await tracker.get(+ task_id, account_id=ctx.account_id, user_id=ctx.user.user_id+ )+ assert task is not None+ assert task.task_type == "snapshot_restore_reindex"+ assert task.status.value == "completed"+ assert ("reindex_file", "viking://resources/proj/x.md") in spy.calls+ finally:+ reset_task_tracker()+++# =========================================================================+# 7. Restore concurrency / locking+# =========================================================================+++async def test_restore_concurrent_same_dir_is_rejected(vfs, monkeypatch):+ """While one restore holds the project_dir tree lock during writeback, a+ second restore on the same subtree fails fast with ResourceBusyError+ (manager default timeout is non-blocking).+ """+ from openviking.storage.errors import ResourceBusyError++ spy = _SpyExecutor()+ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_lock_same")+ await vfs.write_file("viking://resources/proj/a.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", paths=["viking://resources/proj/a.md"], ctx=ctx)+ await vfs.write_file("viking://resources/proj/a.md", b"v2", ctx=ctx)+ await vfs.commit(message="v2", paths=["viking://resources/proj/a.md"], ctx=ctx)++ # Gate the first restore *inside* the writeback so it keeps holding the+ # tree lock while the second restore attempts to acquire it.+ orig_run = vfs._async_agfs.run+ holding_lock = asyncio.Event()+ release = asyncio.Event()++ async def gated_run(method_name, *args, **kwargs):+ if method_name == "git_restore" and not kwargs.get("dry_run"):+ holding_lock.set()+ await release.wait()+ return await orig_run(method_name, *args, **kwargs)++ monkeypatch.setattr(vfs._async_agfs, "run", gated_run)++ first = asyncio.create_task(+ vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ )+ await asyncio.wait_for(holding_lock.wait(), timeout=5)++ # Second restore on the same subtree must be rejected immediately.+ with pytest.raises(ResourceBusyError):+ await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )++ # Release the first restore and let it complete normally.+ release.set()+ result = await asyncio.wait_for(first, timeout=5)+ assert result["result"] == "applied"++ # Lock released: a follow-up restore on the same subtree now succeeds.+ again = await vfs.restore(+ project_dir="viking://resources/proj",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ assert again["result"] in ("applied", "noop")+++async def test_restore_concurrent_sibling_dirs_do_not_block(vfs, monkeypatch):+ """Restores on sibling subtrees hold disjoint tree locks and run+ concurrently — neither blocks the other.+ """+ spy = _SpyExecutor()+ import openviking.service.reindex_executor as reindex_mod+ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)++ ctx = _make_ctx(account="acct_lock_sibling")+ await vfs.write_file("viking://resources/proj_a/x.md", b"v1", ctx=ctx)+ await vfs.write_file("viking://resources/proj_b/y.md", b"v1", ctx=ctx)+ c1 = await vfs.commit(message="v1", ctx=ctx)+ await vfs.write_file("viking://resources/proj_a/x.md", b"v2", ctx=ctx)+ await vfs.write_file("viking://resources/proj_b/y.md", b"v2", ctx=ctx)+ await vfs.commit(message="v2", ctx=ctx)++ # Block both writebacks until both have entered, proving they hold their+ # (distinct) tree locks simultaneously. If the locks conflicted, the second+ # restore would raise ResourceBusyError before reaching git_restore and+ # ``both_in`` would never fire.+ orig_run = vfs._async_agfs.run+ both_in = asyncio.Event()+ release_a = asyncio.Event()+ release_b = asyncio.Event()+ entered = 0++ async def gated_run(method_name, *args, **kwargs):+ nonlocal entered+ if method_name == "git_restore" and not kwargs.get("dry_run"):+ entered += 1+ if entered == 2:+ both_in.set()+ # proj_a is released first; proj_b waits on its own gate.+ await (release_a if kwargs.get("project_dir", "").endswith("proj_a") else release_b).wait()+ return await orig_run(method_name, *args, **kwargs)++ monkeypatch.setattr(vfs._async_agfs, "run", gated_run)++ task_a = asyncio.create_task(+ vfs.restore(+ project_dir="viking://resources/proj_a",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ )+ task_b = asyncio.create_task(+ vfs.restore(+ project_dir="viking://resources/proj_b",+ source_commit=c1["commit_oid"],+ ctx=ctx,+ )+ )+ # Both reaching the writeback concurrently proves the tree locks are disjoint.+ await asyncio.wait_for(both_in.wait(), timeout=5)++ # Drain sequentially: both share branch ``main``, so the final ref CAS would+ # otherwise conflict — that guard is independent of the directory lock.+ release_a.set()+ res_a = await asyncio.wait_for(task_a, timeout=5)+ release_b.set()+ res_b = await asyncio.wait_for(task_b, timeout=5)+ assert res_a["result"] == "applied"+ assert res_b["result"] == "applied"+diff --git a/tests/cli/test_cli_snapshot.py b/tests/cli/test_cli_snapshot.pynew file mode 100644index 000000000..3024d766f--- /dev/null+++ b/tests/cli/test_cli_snapshot.py@@ -0,0 +1,281 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""CLI snapshot (git version control) tests."""++import re+import time+import uuid++import pytest+from conftest import ov++pytestmark = pytest.mark.cli_remote+++def _commit(message: str):+ """Helper: take a snapshot, return the full envelope dict.++ Retries briefly on transient server busy errors.+ """+ r = None+ for _attempt in range(5):+ r = ov(["snapshot", "commit", "-m", message, "-o", "json"], timeout=120)+ if r["exit_code"] == 0:+ break+ if "busy" in r["stderr"].lower() or "internal" in r["stderr"].lower():+ time.sleep(10)+ continue+ break+ assert r["exit_code"] == 0, f"snapshot commit failed: {r['stderr'][:300]}"+ assert r["json"] is not None, f"expected JSON, got: {r['stdout'][:200]}"+ assert r["json"].get("ok") is True, f"expected ok=true, got {r['json']}"+ return r["json"]["result"]+++class TestSnapshotCommit:+ def test_commit_returns_oid_json(self, test_pack_uri):+ # test_pack_uri ensures at least one resource exists+ result = _commit(f"cli-test commit {uuid.uuid4().hex[:6]}")+ assert "commit_oid" in result, f"expected commit_oid in result, got {result}"+ assert isinstance(result["commit_oid"], str) and len(result["commit_oid"]) >= 12++ def test_commit_human_prints_short_oid(self, test_pack_uri):+ msg = f"cli-test human {uuid.uuid4().hex[:6]}"+ r = ov(["snapshot", "commit", "-m", msg], timeout=120)+ assert r["exit_code"] == 0, f"snapshot commit failed: {r['stderr'][:300]}"+ out = r["stdout"]+ assert re.match(+ r"^(Created [0-9a-f]{12}|No changes)", out+ ), f"unexpected commit stdout: {out[:200]}"+++class TestSnapshotLog:+ def test_log_lists_commits(self, test_pack_uri):+ r_before = ov(["snapshot", "log", "--limit", "100"], timeout=60)+ assert r_before["exit_code"] == 0+ before_lines = [ln for ln in r_before["stdout"].splitlines() if ln.strip()]++ commit = _commit(f"log-test setup {uuid.uuid4().hex[:6]}")+ short_oid = commit["commit_oid"][:12]++ r_after = ov(["snapshot", "log", "--limit", "100"], timeout=60)+ assert r_after["exit_code"] == 0+ after_lines = [ln for ln in r_after["stdout"].splitlines() if ln.strip()]++ # The new commit's short oid must appear in the log, proving log reflects HEAD.+ assert any(short_oid in ln for ln in after_lines), (+ f"new commit {short_oid} should appear in log; "+ f"first few lines: {after_lines[:3]}"+ )+ # A single commit should add at most one row (noop commits add zero).+ delta = len(after_lines) - len(before_lines)+ assert 0 <= delta <= 1, (+ f"expected log delta of 0 or 1 after one commit, got {delta} "+ f"(before={len(before_lines)}, after={len(after_lines)})"+ )++ def test_log_json_returns_array(self, test_pack_uri):+ _commit(f"log-json setup {uuid.uuid4().hex[:6]}")+ r = ov(["snapshot", "log", "--limit", "5", "-o", "json"], timeout=60)+ assert r["exit_code"] == 0, f"snapshot log -o json failed: {r['stderr'][:300]}"+ # Server returns {"ok": true, "result": [...]}, so r["json"] works+ assert r["json"] is not None, f"expected JSON, got: {r['stdout'][:200]}"+ assert r["json"].get("ok") is True+ result = r["json"]["result"]+ assert isinstance(result, list), f"expected list, got {type(result).__name__}: {result}"+ assert len(result) >= 1+ first = result[0]+ assert "oid" in first and "message" in first+++class TestSnapshotShow:+ def test_show_metadata(self, test_pack_uri):+ commit = _commit(f"show-meta setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]+ r = ov(["snapshot", "show", oid, "-o", "json"], timeout=60)+ assert r["exit_code"] == 0, f"snapshot show failed: {r['stderr'][:300]}"+ assert r["json"] is not None and r["json"].get("ok") is True+ meta = r["json"]["result"]+ assert meta.get("oid") == oid or meta.get("oid", "").startswith(oid[:12])+ assert "tree" in meta and "author" in meta++ def test_show_blob_to_stdout(self, test_file_uri, tmp_path):+ commit = _commit(f"show-stdout setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]++ # Capture canonical bytes via `get` (writes the file directly — no shell echo+ # framing).+ canonical_path = tmp_path / "canonical.bin"+ r_get = ov(+ ["get", test_file_uri, str(canonical_path), "-o", "json"],+ timeout=60,+ )+ assert r_get["exit_code"] == 0, f"get failed: {r_get['stderr'][:300]}"+ expected_bytes = canonical_path.read_bytes()++ r_show = ov(["snapshot", "show", oid, "--path", test_file_uri], timeout=60)+ assert r_show["exit_code"] == 0, f"snapshot show failed: {r_show['stderr'][:300]}"++ # `ov()` returns stdout as a stripped str; the CLI's `echo_command=True` may+ # prepend the command line. Locate the blob body by suffix match: stdout must+ # end with the file's content (with the encoding `ov()` used to decode bytes).+ try:+ expected_text = expected_bytes.decode("utf-8")+ except UnicodeDecodeError:+ pytest.skip("fixture content is not utf-8; this test assumes a text blob")+ assert r_show["stdout"].endswith(expected_text.rstrip()), (+ f"snapshot show stdout did not end with canonical blob content; "+ f"tail of show stdout: {r_show['stdout'][-200:]!r} vs "+ f"expected tail: {expected_text[-200:]!r}"+ )++ def test_show_blob_to_file(self, test_file_uri, tmp_path):+ commit = _commit(f"show-blob setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]++ canonical_path = tmp_path / "canonical.bin"+ r_get = ov(+ ["get", test_file_uri, str(canonical_path), "-o", "json"],+ timeout=60,+ )+ assert r_get["exit_code"] == 0, f"get failed: {r_get['stderr'][:300]}"+ expected_bytes = canonical_path.read_bytes()++ out_path = tmp_path / "blob.bin"+ r = ov(+ [+ "snapshot",+ "show",+ oid,+ "--path",+ test_file_uri,+ "--out-file",+ str(out_path),+ ],+ timeout=60,+ )+ assert r["exit_code"] == 0, f"snapshot show --out-file failed: {r['stderr'][:300]}"+ assert out_path.exists(), f"out-file {out_path} should exist"++ contents = out_path.read_bytes()+ assert contents == expected_bytes, (+ f"out-file bytes ({len(contents)} bytes) should match canonical "+ f"({len(expected_bytes)} bytes)"+ )+ # Stderr summary must report bytes + blob-oid + path.+ # Note: the oid in the summary is the *blob* oid (from X-Snapshot-Oid),+ # not the commit oid.+ import re as _re+ assert (+ "Wrote" in r["stderr"]+ and "bytes from" in r["stderr"]+ and _re.search(r"from [0-9a-f]{7,}", r["stderr"])+ and str(out_path) in r["stderr"]+ ), f"missing stderr summary, got: {r['stderr'][:300]}"++ def test_show_blob_stdout_byte_exact_via_subprocess(self, test_file_uri, tmp_path):+ """Run `snapshot show --path X` without --out-file and capture raw+ bytes — must match the file content exactly (no UTF-8 decoding, no+ trailing-newline tolerance). The `ov()` helper decodes as text and+ strips, which hides binary-mangling bugs.+ """+ import subprocess+ from conftest import CLI_BIN, _env, _inject_global_args++ commit = _commit(f"show-stdout-bytes setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]++ canonical_path = tmp_path / "canonical.bin"+ r_get = ov(+ ["get", test_file_uri, str(canonical_path), "-o", "json"], timeout=60+ )+ assert r_get["exit_code"] == 0, f"get failed: {r_get['stderr'][:300]}"+ expected_bytes = canonical_path.read_bytes()++ # Run the CLI ourselves so we can capture stdout as bytes.+ args = _inject_global_args(["snapshot", "show", oid, "--path", test_file_uri])+ proc = subprocess.run(+ [CLI_BIN] + args,+ capture_output=True,+ timeout=60,+ env=_env(),+ )+ assert proc.returncode == 0, (+ f"snapshot show stdout exit={proc.returncode}, "+ f"stderr={proc.stderr.decode('utf-8', errors='replace')[:300]}"+ )++ # The CLI's echo_command prefix may land on stdout. Bytes must+ # END with the canonical payload (no decoding, no rstrip).+ assert proc.stdout.endswith(expected_bytes), (+ f"snapshot show stdout did not end with canonical bytes; "+ f"got tail (hex): {proc.stdout[-64:].hex()} vs "+ f"expected tail (hex): {expected_bytes[-64:].hex()}"+ )++ # The stderr summary line ("Read N bytes from <blob-oid>") must be+ # present — this is the user-visible signal that bytes flowed.+ # The oid in the summary is the blob oid (X-Snapshot-Oid), not the+ # commit oid we asked about.+ import re as _re+ stderr_text = proc.stderr.decode("utf-8", errors="replace")+ assert (+ "Read" in stderr_text+ and "bytes from" in stderr_text+ and _re.search(r"from [0-9a-f]{7,}", stderr_text)+ ), f"expected stderr summary 'Read N bytes from <blob-oid>', got: {stderr_text[:300]}"+++class TestSnapshotRestore:+ def test_restore_dry_run_does_not_mutate(self, test_pack_uri):+ # Capture ls before+ ls_before = ov(["ls", "viking://resources", "-r", "-o", "json", "-n", "50"], timeout=60)+ assert ls_before["exit_code"] == 0++ commit = _commit(f"restore-dry setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]+ r = ov(+ [+ "snapshot",+ "restore",+ oid,+ "viking://resources",+ "--dry-run",+ "-o",+ "json",+ ],+ timeout=60,+ )+ assert r["exit_code"] == 0, f"snapshot restore --dry-run failed: {r['stderr'][:300]}"+ assert r["json"] is not None and r["json"].get("ok") is True+ result = r["json"]["result"]+ # Dry-run shape includes a "diff" key+ assert "diff" in result, f"expected diff in dry-run result, got keys: {list(result.keys())}"++ # ls should be unchanged after dry-run+ ls_after = ov(["ls", "viking://resources", "-r", "-o", "json", "-n", "50"], timeout=60)+ assert ls_after["exit_code"] == 0+ # Compare result lists if both present+ if ls_before["json"] and ls_after["json"]:+ assert ls_before["json"].get("result") == ls_after["json"].get("result"), (+ "ls output should be unchanged after dry-run restore"+ )++ def test_restore_dry_run_without_project_dir(self, test_pack_uri):+ commit = _commit(f"restore-full-dry setup {uuid.uuid4().hex[:6]}")+ oid = commit["commit_oid"]+ r = ov(+ [+ "snapshot",+ "restore",+ oid,+ "--dry-run",+ "-o",+ "json",+ ],+ timeout=60,+ )+ assert r["exit_code"] == 0, f"snapshot restore full --dry-run failed: {r['stderr'][:300]}"+ assert r["json"] is not None and r["json"].get("ok") is True+ result = r["json"]["result"]+ assert "diff" in result or result.get("result") == "noop"diff --git a/tests/client/test_git_versioning.py b/tests/client/test_git_versioning.pynew file mode 100644index 000000000..3edc0d895--- /dev/null+++ b/tests/client/test_git_versioning.py@@ -0,0 +1,347 @@+"""End-to-end tests for the OpenViking.snapshot namespace.++These exercise the user-facing namespace path:+OpenViking -> LocalClient -> FSService -> VikingFS -> RAGFSBindingClient -> Rust GitService.+"""++from __future__ import annotations++import re+import shutil+import tempfile+from pathlib import Path+from typing import NamedTuple, Tuple+from unittest.mock import MagicMock++import pytest++ragfs_python = pytest.importorskip("ragfs_python")++from openviking.async_client import AsyncOpenViking+from openviking.client.local import LocalClient+from openviking.pyagfs.exceptions import AGFSNotSupportedError+from openviking.server.identity import RequestContext, Role+from openviking_cli.exceptions import InvalidURIError+from openviking.service.fs_service import FSService+from openviking.storage.viking_fs import VikingFS+from openviking.sync_client import SyncOpenViking+from openviking_cli.session.user_id import UserIdentifier+++OID_RE = re.compile(r"^[0-9a-f]{40}$")+DEFAULT_AUTHOR_NAME = VikingFS._DEFAULT_GIT_AUTHOR_NAME+++class ClientHarness(NamedTuple):+ client: SyncOpenViking+ async_client: AsyncOpenViking+ vfs: VikingFS+ ctx: RequestContext+++def _make_ctx(account: str = "acct_t", user: str = "user1") -> RequestContext:+ return RequestContext(user=UserIdentifier(account, user), role=Role.ROOT)+++def _write_workspace(tmp_root: Path) -> Tuple[Path, Path]:+ """Create ragfs config and backing localfs root for git-enabled tests."""+ fs_root = tmp_root / "fs"+ git_root = tmp_root / "git"+ fs_root.mkdir(parents=True, exist_ok=True)+ git_root.mkdir(parents=True, exist_ok=True)+ cfg = tmp_root / "ragfs.toml"+ cfg.write_text(+ f"""+[git]+enabled = true+backend = "local"+default_branch = "main"+author_name = "test-bot"+author_email = "[email protected]"++[git.local]+base_dir = "{git_root}"+"""+ )+ return cfg, fs_root+++def _write_disabled_workspace(tmp_root: Path) -> Tuple[Path, Path]:+ fs_root = tmp_root / "fs"+ fs_root.mkdir(parents=True, exist_ok=True)+ cfg = tmp_root / "ragfs.toml"+ cfg.write_text(+ """+[git]+enabled = false+"""+ )+ return cfg, fs_root+++def _build_binding_client(config_path: Path, fs_root: Path):+ client = ragfs_python.RAGFSBindingClient(git_config_path=str(config_path))+ client.mount("localfs", "/local", {"local_dir": str(fs_root)})+ return client+++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()+ fs_service.set_dependencies(viking_fs=vfs)++ local_client = object.__new__(LocalClient)+ local_client._service = MagicMock()+ local_client._service.fs = fs_service+ local_client._ctx = ctx++ async_client = object.__new__(AsyncOpenViking)+ async_client._client = local_client+ async_client._initialized = True+ async_client._singleton_initialized = True+ async_client._snapshot = None++ sync_client = object.__new__(SyncOpenViking)+ sync_client._async_client = async_client+ sync_client._initialized = True+ sync_client._snapshot = None++ return ClientHarness(+ client=sync_client,+ async_client=async_client,+ vfs=vfs,+ ctx=ctx,+ )+++def workspace():+ root = Path(tempfile.mkdtemp(prefix="ov-client-git-"))+ try:+ yield root+ finally:+ shutil.rmtree(root, ignore_errors=True)+++def git_harness(workspace) -> ClientHarness:+ from openviking.storage.transaction import reset_lock_manager++ cfg, fs_root = _write_workspace(workspace)+ try:+ yield _build_harness(cfg, fs_root)+ finally:+ reset_lock_manager()+++def git_disabled_harness(workspace) -> ClientHarness:+ from openviking.storage.transaction import reset_lock_manager++ cfg, fs_root = _write_disabled_workspace(workspace)+ try:+ yield _build_harness(cfg, fs_root)+ finally:+ reset_lock_manager()+++async def test_write_commit_show_roundtrip(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/a.md",+ b"hello",+ ctx=git_harness.ctx,+ )++ commit = git_harness.client.snapshot.commit(+ message="initial",+ paths=["viking://resources/a.md"],+ )++ 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"+++async def test_show_metadata_without_path(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/meta.md",+ b"metadata",+ ctx=git_harness.ctx,+ )+ commit = git_harness.client.snapshot.commit(+ message="metadata commit",+ paths=["viking://resources/meta.md"],+ )++ metadata = git_harness.client.snapshot.show("main")++ assert metadata["oid"] == commit["commit_oid"]+ assert metadata["message"].startswith("metadata commit")+ assert metadata["author"]["name"] == DEFAULT_AUTHOR_NAME+ assert metadata["parents"] == []+++async def test_log_walks_parents(git_harness):+ commits = []+ for idx, body in enumerate((b"v1", b"v2", b"v3"), start=1):+ await git_harness.vfs.write_file(+ "viking://resources/log.md",+ body,+ ctx=git_harness.ctx,+ )+ commits.append(+ git_harness.client.snapshot.commit(+ message=f"c{idx}",+ paths=["viking://resources/log.md"],+ )+ )++ history = git_harness.client.snapshot.log(limit=10)+ limited = git_harness.client.snapshot.log(limit=2)++ assert [item["oid"] for item in history] == [+ commits[2]["commit_oid"],+ commits[1]["commit_oid"],+ commits[0]["commit_oid"],+ ]+ assert [item["oid"] for item in limited] == [+ commits[2]["commit_oid"],+ commits[1]["commit_oid"],+ ]+++async def test_restore_reverts_file_and_advances_head(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/proj/a.md",+ b"v1",+ ctx=git_harness.ctx,+ )+ v1 = git_harness.client.snapshot.commit(+ message="v1",+ paths=["viking://resources/proj/a.md"],+ )++ await git_harness.vfs.write_file(+ "viking://resources/proj/a.md",+ b"v2",+ ctx=git_harness.ctx,+ )+ v2 = git_harness.client.snapshot.commit(+ message="v2",+ paths=["viking://resources/proj/a.md"],+ )++ restore = git_harness.client.snapshot.restore(+ project_dir="viking://resources/proj",+ source_commit=v1["commit_oid"],+ )++ assert restore["result"] == "applied"+ 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 git_harness.client.snapshot.show("main")["parents"] == [v2["commit_oid"]]+++async def test_restore_dry_run_does_not_mutate(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/proj/a.md",+ b"v1",+ ctx=git_harness.ctx,+ )+ v1 = git_harness.client.snapshot.commit(+ message="v1",+ paths=["viking://resources/proj/a.md"],+ )+ await git_harness.vfs.write_file(+ "viking://resources/proj/a.md",+ b"v2",+ ctx=git_harness.ctx,+ )+ git_harness.client.snapshot.commit(+ message="v2",+ paths=["viking://resources/proj/a.md"],+ )+ before_log = git_harness.client.snapshot.log()++ dry_run = git_harness.client.snapshot.restore(+ project_dir="viking://resources/proj",+ source_commit=v1["commit_oid"],+ dry_run=True,+ )++ 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 len(git_harness.client.snapshot.log()) == len(before_log)+++async def test_restore_internal_scope_rejected(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/a.md",+ b"content",+ ctx=git_harness.ctx,+ )+ commit = git_harness.client.snapshot.commit(+ message="commit",+ paths=["viking://resources/a.md"],+ )++ # Client-level calls cross FSService first; its URI validator rejects+ # internal scopes before VikingFS.restore can raise ValueError.+ with pytest.raises(InvalidURIError):+ git_harness.client.snapshot.restore(+ project_dir="viking://temp/x",+ source_commit=commit["commit_oid"],+ )+++async def test_disabled_raises_not_supported(git_disabled_harness):+ with pytest.raises(AGFSNotSupportedError):+ git_disabled_harness.client.snapshot.commit(message="disabled")+ with pytest.raises(AGFSNotSupportedError):+ git_disabled_harness.client.snapshot.show("main")+ with pytest.raises(AGFSNotSupportedError):+ git_disabled_harness.client.snapshot.restore(+ project_dir="viking://resources/proj",+ source_commit="main",+ )+ with pytest.raises(AGFSNotSupportedError):+ git_disabled_harness.client.snapshot.log()+++async def test_async_api_parity(git_harness):+ await git_harness.vfs.write_file(+ "viking://resources/async.md",+ b"async hello",+ ctx=git_harness.ctx,+ )++ commit = await git_harness.async_client.snapshot.commit(+ message="async initial",+ paths=["viking://resources/async.md"],+ )+ body = await git_harness.async_client.snapshot.show(+ "main",+ path="viking://resources/async.md",+ )++ assert commit["result"] == "created"+ assert OID_RE.match(commit["commit_oid"])+ assert body == b"async hello"diff --git a/tests/client/test_git_versioning_http.py b/tests/client/test_git_versioning_http.pynew file mode 100644index 000000000..ae680496c--- /dev/null+++ b/tests/client/test_git_versioning_http.py@@ -0,0 +1,241 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""End-to-end parity tests for client.snapshot.* over HTTP.++These exercise the AsyncHTTPClient.snapshot namespace surface that mirrors+the LocalClient.snapshot surface covered by tests/client/test_git_versioning.py,+routed through AsyncHTTPClient -> real FastAPI server (via httpx+ASGITransport) -> real OpenVikingService -> real VikingFS.++The full stack is genuine: real httpx response parsing, real envelope+handling, real X-Snapshot-* header round-tripping. No mocks at the+client.snapshot or AsyncHTTPClient layer.+"""++from __future__ import annotations++import re+import shutil+import uuid+from pathlib import Path+from typing import AsyncGenerator++import httpx+import pytest+import pytest_asyncio++ragfs_python = pytest.importorskip("ragfs_python")++from openviking.models.embedder.base import DenseEmbedderBase, EmbedResult+from openviking.server.app import create_app+from openviking.server.config import ServerConfig+from openviking.server.identity import RequestContext, Role+from openviking.service.core import OpenVikingService+from openviking.storage.transaction import reset_lock_manager+from openviking_cli.client.http import AsyncHTTPClient+from openviking_cli.session.user_id import UserIdentifier+from openviking_cli.utils.config.embedding_config import EmbeddingConfig+from openviking_cli.utils.config.vlm_config import VLMConfig+++pytestmark = pytest.mark.asyncio++OID_RE = re.compile(r"^[0-9a-f]{40}$")++PROJECT_ROOT = Path(__file__).parent.parent.parent+HTTP_TEST_TMP_DIR = PROJECT_ROOT / "test_data" / "tmp_client_git_http"+++def _install_fake_embedder(monkeypatch):+ dimension = 1024++ class FakeEmbedder(DenseEmbedderBase):+ def __init__(self):+ super().__init__(model_name="test-fake-embedder")++ def embed(self, text: str, is_query: bool = False) -> EmbedResult:+ return EmbedResult(dense_vector=[0.1] * dimension)++ def embed_batch(self, texts, is_query: bool = False):+ return [self.embed(t, is_query=is_query) for t in texts]++ def get_dimension(self) -> int:+ return dimension++ monkeypatch.setattr(EmbeddingConfig, "get_embedder", lambda self: FakeEmbedder())+ return FakeEmbedder+++def _install_fake_vlm(monkeypatch):+ async def _fake_get_completion(self, prompt, thinking=False):+ return "fake summary"++ async def _fake_get_vision_completion(self, prompt, images, thinking=False):+ return "fake vision"++ monkeypatch.setattr(VLMConfig, "is_available", lambda self: True)+ monkeypatch.setattr(VLMConfig, "get_completion_async", _fake_get_completion)+ monkeypatch.setattr(VLMConfig, "get_vision_completion_async", _fake_get_vision_completion)++[email protected](scope="function")+def http_temp_dir():+ unique = HTTP_TEST_TMP_DIR / uuid.uuid4().hex[:8]+ unique.mkdir(parents=True, exist_ok=True)+ yield unique+ shutil.rmtree(unique, ignore_errors=True)+++@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)++ svc = OpenVikingService(+ path=str(http_temp_dir / "data"),+ user=UserIdentifier.the_default_user("git_http_test_user"),+ )+ await svc.initialize()+ svc.viking_fs.query_embedder = fake_embedder_cls()++ test_ctx = RequestContext(+ user=UserIdentifier("git_http_test_account", "git_http_test_user"),+ role=Role.ADMIN,+ )+ await svc.initialize_account_directories(test_ctx)+ await svc.initialize_user_directories(test_ctx)+ try:+ yield svc+ finally:+ await svc.close()+ reset_lock_manager()+++@pytest_asyncio.fixture(scope="function")+async def http_app(http_service: OpenVikingService):+ """FastAPI app with the test service wired in (no auth)."""+ from openviking.server.auth.plugins import DevAuthPlugin+ from openviking.server.auth.registry import get_registry+ from openviking.server.dependencies import set_service++ config = ServerConfig()+ app = create_app(config=config, service=http_service)+ set_service(http_service)+ # ASGITransport doesn't trigger lifespan, so wire up the auth plugin manually.+ registry = get_registry()+ if registry.get("dev") is None:+ registry.register(DevAuthPlugin)+ app.state.auth_plugin = registry.get("dev")()+ return app+++@pytest_asyncio.fixture(scope="function")+async def http_git_client(http_app) -> AsyncGenerator[AsyncHTTPClient, None]:+ """Real AsyncHTTPClient whose underlying httpx talks to the ASGI app.++ The returned client exposes the production `.snapshot` namespace; the only+ swap is the transport — every other layer is the real stack.+ """+ client = AsyncHTTPClient(+ url="http://testserver",+ api_key="test-key",+ account="git_http_test_account",+ user="git_http_test_user",+ )+ transport = httpx.ASGITransport(app=http_app)+ headers = {+ "X-API-Key": "test-key",+ "X-OpenViking-Account": "git_http_test_account",+ "X-OpenViking-User": "git_http_test_user",+ }+ client._http = httpx.AsyncClient(+ transport=transport,+ base_url="http://testserver",+ headers=headers,+ timeout=30.0,+ )+ try:+ yield client+ finally:+ await client._http.aclose()+++async def _write_blob(service: OpenVikingService, uri: str, body: bytes) -> None:+ ctx = RequestContext(+ user=UserIdentifier("git_http_test_account", "git_http_test_user"),+ role=Role.ROOT,+ )+ await service.viking_fs.write_file(uri, body, ctx=ctx)+++async def test_http_commit_and_log_roundtrip(http_git_client, http_service):+ client = http_git_client++ await _write_blob(http_service, "viking://resources/http_a.md", b"hello-http")++ commit = await client.snapshot.commit(message="http parity")+ assert commit["result"] in ("created", "noop")+ assert isinstance(commit["commit_oid"], str)+ assert OID_RE.match(commit["commit_oid"])++ log = await client.snapshot.log(limit=5)+ assert isinstance(log, list) and len(log) >= 1+ assert "oid" in log[0] and "message" in log[0]+++async def test_http_show_blob_byte_exact_roundtrip(http_git_client, http_service):+ client = http_git_client+ blob_uri = "viking://resources/http_show_blob.txt"+ expected = b"byte exact \x00\x01\x02 payload\n"++ await _write_blob(http_service, blob_uri, expected)+ commit = await client.snapshot.commit(message="with blob")+ assert OID_RE.match(commit["commit_oid"])++ result = await client.snapshot.show(commit["commit_oid"], path=blob_uri)+ assert isinstance(result, dict)+ assert result["bytes"] == expected+ assert result["size"] == len(expected)+ assert OID_RE.match(result["oid"])+++async def test_http_show_metadata_without_path(http_git_client, http_service):+ client = http_git_client++ await _write_blob(http_service, "viking://resources/http_meta.md", b"metadata")+ commit = await client.snapshot.commit(message="meta commit")++ meta = await client.snapshot.show(commit["commit_oid"])+ assert meta["oid"] == commit["commit_oid"]+ assert meta["message"].startswith("meta commit")+ assert meta["parents"] == []+++async def test_http_restore_dry_run_does_not_mutate(http_git_client, http_service):+ client = http_git_client++ await _write_blob(http_service, "viking://resources/proj/a.md", b"v1")+ v1 = await client.snapshot.commit(message="v1")+ assert OID_RE.match(v1["commit_oid"])++ await _write_blob(http_service, "viking://resources/proj/a.md", b"v2")+ v2 = await client.snapshot.commit(message="v2")+ assert v2["commit_oid"] != v1["commit_oid"]++ log_before = await client.snapshot.log(limit=10)++ dry = await client.snapshot.restore(+ project_dir="viking://resources/proj",+ source_commit=v1["commit_oid"],+ dry_run=True,+ )++ assert "diff" in dry or dry.get("result") == "noop"++ blob_after = await client.snapshot.show(v2["commit_oid"], path="viking://resources/proj/a.md")+ assert blob_after["bytes"] == b"v2"++ log_after = await client.snapshot.log(limit=10)+ assert len(log_after) == len(log_before)diff --git a/tests/client/test_http_client_snapshot.py b/tests/client/test_http_client_snapshot.pynew file mode 100644index 000000000..94c576940--- /dev/null+++ b/tests/client/test_http_client_snapshot.py@@ -0,0 +1,214 @@+"""Unit tests for AsyncHTTPClient git_* methods that drive /api/v1/snapshot/*."""++from typing import Any, Dict, List, Optional++import pytest++from openviking_cli.client.http import AsyncHTTPClient++pytestmark = pytest.mark.asyncio+++class _FakeHTTPClient:+ """Records the last request and returns a canned response."""++ def __init__(self):+ self.calls: List[Dict[str, Any]] = []+ self.next_response: Any = None++ async def get(self, path, *, params=None, headers=None):+ self.calls.append({"method": "GET", "path": path, "params": params, "headers": headers})+ return self.next_response++ async def post(self, path, *, json=None, headers=None):+ self.calls.append({"method": "POST", "path": path, "json": json, "headers": headers})+ return self.next_response+++def _client_with_fake() -> tuple[AsyncHTTPClient, _FakeHTTPClient]:+ client = AsyncHTTPClient(url="http://localhost:1933")+ fake = _FakeHTTPClient()+ client._http = fake+ client._handle_response = lambda response: {"commit_oid": "a" * 40, "result": "created", "changed": 1}+ return client, fake+++async def test_git_commit_posts_to_snapshot_commit():+ client, fake = _client_with_fake()+ fake.next_response = object()++ result = await client.git_commit(+ message="hello",+ paths=["viking://resources/a.md"],+ branch="main",+ author_name="bot",+ author_email="[email protected]",+ )++ assert result == {"commit_oid": "a" * 40, "result": "created", "changed": 1}+ call = fake.calls[-1]+ assert call["method"] == "POST"+ assert call["path"] == "/api/v1/snapshot/commit"+ assert call["json"] == {+ "message": "hello",+ "paths": ["viking://resources/a.md"],+ "branch": "main",+ "author_name": "bot",+ "author_email": "[email protected]",+ }+++async def test_git_commit_omits_none_fields():+ client, fake = _client_with_fake()+ fake.next_response = object()++ await client.git_commit(message="hi")++ call = fake.calls[-1]+ assert call["json"] == {"message": "hi", "branch": "main"}+++async def test_git_restore_omits_project_dir_when_none():+ client, fake = _client_with_fake()+ client._handle_response = lambda resp: {"result": "noop", "head": "h" * 40, "source": "s" * 40}+ fake.next_response = object()++ result = await client.git_restore(+ source_commit="s" * 40,+ dry_run=True,+ )++ assert result["result"] == "noop"+ call = fake.calls[-1]+ assert call["method"] == "POST"+ assert call["path"] == "/api/v1/snapshot/restore"+ assert call["json"] == {+ "source_commit": "s" * 40,+ "branch": "main",+ "dry_run": True,+ }+++async def test_git_restore_includes_project_dir_when_provided():+ client, fake = _client_with_fake()+ client._handle_response = lambda resp: {"result": "noop", "head": "h" * 40, "source": "s" * 40}+ fake.next_response = object()++ await client.git_restore(+ project_dir="viking://resources",+ source_commit="s" * 40,+ dry_run=True,+ )++ call = fake.calls[-1]+ assert call["json"] == {+ "source_commit": "s" * 40,+ "branch": "main",+ "dry_run": True,+ "project_dir": "viking://resources",+ }+++class _FakeBinaryResponse:+ """Mimics enough of httpx.Response for the show-blob branch."""++ def __init__(self, content: bytes, oid: str, size: int):+ self.content = content+ self.status_code = 200+ self.headers = {+ "content-type": "application/octet-stream",+ "x-snapshot-oid": oid,+ "x-snapshot-size": str(size),+ }+++async def test_git_show_metadata_uses_handle_response():+ client, fake = _client_with_fake()+ client._handle_response = lambda resp: {"oid": "c" * 40, "tree": "t" * 40, "message": "m"}+ fake.next_response = type("R", (), {"headers": {"content-type": "application/json"}})()++ result = await client.git_show(target_ref="c" * 40)++ assert result == {"oid": "c" * 40, "tree": "t" * 40, "message": "m"}+ call = fake.calls[-1]+ assert call["method"] == "GET"+ assert call["path"] == "/api/v1/snapshot/show"+ assert call["params"] == {"target_ref": "c" * 40}+++async def test_git_show_blob_returns_envelope_from_headers():+ client = AsyncHTTPClient(url="http://localhost:1933")+ fake = _FakeHTTPClient()+ client._http = fake++ fake.next_response = _FakeBinaryResponse(b"hello\n", oid="b" * 40, size=6)++ result = await client.git_show(target_ref="c" * 40, path="viking://resources/x.txt")++ assert result == {"oid": "b" * 40, "size": 6, "bytes": b"hello\n"}+ call = fake.calls[-1]+ assert call["params"] == {"target_ref": "c" * 40, "path": "viking://resources/x.txt"}+++async def test_git_show_blob_handles_case_insensitive_headers():+ """A real httpx.Response uses case-insensitive headers (httpx.Headers).+ Confirm the client reads x-snapshot-* correctly even when the server+ capitalises them (FastAPI may send X-Snapshot-Oid as-is).+ """+ import httpx++ client = AsyncHTTPClient(url="http://localhost:1933")+ fake = _FakeHTTPClient()+ client._http = fake++ class _CaseyResponse:+ def __init__(self, content: bytes, oid: str, size: int):+ self.content = content+ self.status_code = 200+ self.headers = httpx.Headers(+ {+ "Content-Type": "application/octet-stream",+ "X-Snapshot-Oid": oid,+ "X-Snapshot-Size": str(size),+ }+ )++ fake.next_response = _CaseyResponse(b"\x00\x01\x02", oid="e" * 40, size=3)+ result = await client.git_show(target_ref="ref", path="viking://resources/bin.dat")+ assert result == {"oid": "e" * 40, "size": 3, "bytes": b"\x00\x01\x02"}+++async def test_git_show_blob_missing_headers_degrades_gracefully():+ """Server bug / proxy strip: headers absent but content-type still binary.+ Client must not crash — empty oid and size=0 are acceptable fallbacks+ (the byte payload is what matters for the caller).+ """+ client = AsyncHTTPClient(url="http://localhost:1933")+ fake = _FakeHTTPClient()+ client._http = fake++ class _NoHeadersResponse:+ def __init__(self, content: bytes):+ self.content = content+ self.status_code = 200+ self.headers = {"content-type": "application/octet-stream"}++ fake.next_response = _NoHeadersResponse(b"payload")+ result = await client.git_show(target_ref="r", path="viking://resources/x")+ assert result["bytes"] == b"payload"+ assert result["oid"] == ""+ assert result["size"] == 0+++async def test_git_log_gets_with_params():+ client, fake = _client_with_fake()+ client._handle_response = lambda resp: [{"oid": "d" * 40, "message": "x"}]+ fake.next_response = object()++ result = await client.git_log(branch="main", limit=5)++ assert result == [{"oid": "d" * 40, "message": "x"}]+ call = fake.calls[-1]+ assert call["method"] == "GET"+ assert call["path"] == "/api/v1/snapshot/log"+ assert call["params"] == {"branch": "main", "limit": 5}diff --git a/tests/server/test_api_snapshot.py b/tests/server/test_api_snapshot.pynew file mode 100644index 000000000..a83defd49--- /dev/null+++ b/tests/server/test_api_snapshot.py@@ -0,0 +1,441 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""End-to-end tests for /api/v1/snapshot/*."""++import pytest+import pytest_asyncio++import httpx++pytestmark = pytest.mark.asyncio+++@pytest_asyncio.fixture(scope="function")+async def client_with_no_repo(app):+ """Plain in-process client with no resources or commits added.++ The conftest's ``app`` fixture wires the service into the global+ dependency store without authentication, so a vanilla AsyncClient+ is enough to hit ``/api/v1/snapshot/log`` against an empty repo.+ """+ transport = httpx.ASGITransport(app=app)+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:+ yield c+++async def test_commit_creates_snapshot(client_with_resource):+ client, _root_uri = client_with_resource+ resp = await client.post(+ "/api/v1/snapshot/commit",+ json={"message": "first snapshot"},+ )+ assert resp.status_code == 200, resp.text+ body = resp.json()+ assert body["status"] == "ok"+ result = body["result"]+ assert result["result"] in ("created", "noop")+ assert isinstance(result["commit_oid"], str) and len(result["commit_oid"]) == 40+++async def test_log_returns_recent_commits(client_with_resource):+ client, _ = client_with_resource+ await client.post("/api/v1/snapshot/commit", json={"message": "for log"})++ resp = await client.get("/api/v1/snapshot/log", params={"branch": "main", "limit": 5})+ assert resp.status_code == 200, resp.text+ body = resp.json()+ assert body["status"] == "ok"+ log = body["result"]+ assert isinstance(log, list) and len(log) >= 1+ assert "oid" in log[0] and "message" in log[0]+++async def test_log_empty_repo_returns_404(client_with_no_repo):+ """When the branch has no commits, /log should surface 404."""+ client = client_with_no_repo+ resp = await client.get("/api/v1/snapshot/log", params={"branch": "main", "limit": 5})+ assert resp.status_code == 404+ assert resp.json()["status"] == "error"+++@pytest_asyncio.fixture(scope="function")+async def client_with_resource_and_blob(client_with_resource, service):+ """client_with_resource + a known blob written via VikingFS.write_file, then committed."""+ from openviking.server.identity import RequestContext, Role+ from openviking_cli.session.user_id import UserIdentifier++ client, _root = client_with_resource+ blob_uri = "viking://resources/snapshot_blob_fixture.txt"+ expected_bytes = b"hello from snapshot fixture\n"++ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)+ await service.viking_fs.write_file(blob_uri, expected_bytes, ctx=ctx)++ commit_resp = await client.post(+ "/api/v1/snapshot/commit",+ json={"message": "with blob"},+ )+ assert commit_resp.status_code == 200, commit_resp.text+ commit_oid = commit_resp.json()["result"]["commit_oid"]++ yield client, commit_oid, blob_uri, expected_bytes+++async def test_restore_dry_run_does_not_mutate(client_with_resource):+ client, _root = client_with_resource+ v1 = (await client.post("/api/v1/snapshot/commit", json={"message": "v1"})).json()["result"]++ resp = await client.post(+ "/api/v1/snapshot/restore",+ json={+ "project_dir": "viking://resources",+ "source_commit": v1["commit_oid"],+ "dry_run": True,+ },+ )+ assert resp.status_code == 200, resp.text+ body = resp.json()+ assert body["status"] == "ok"+ result = body["result"]+ # Per VikingFS.restore contract, dry_run responses carry 'diff'.+ assert "diff" in result or result.get("result") == "noop"+++async def test_show_commit_metadata(client_with_resource):+ client, _ = client_with_resource+ commit = (await client.post("/api/v1/snapshot/commit", json={"message": "meta"})).json()["result"]+ resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": commit["commit_oid"]},+ )+ assert resp.status_code == 200+ body = resp.json()+ assert body["status"] == "ok"+ meta = body["result"]+ assert meta["oid"] == commit["commit_oid"]+ assert "tree" in meta and "message" in meta+++async def test_show_blob_returns_binary_with_headers(client_with_resource_and_blob):+ """show?path=<file> must return raw bytes + X-Snapshot-* headers."""+ client, commit_oid, blob_uri, expected_bytes = client_with_resource_and_blob+ resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": commit_oid, "path": blob_uri},+ )+ assert resp.status_code == 200+ assert resp.headers["content-type"].startswith("application/octet-stream")+ assert "x-snapshot-oid" in {k.lower() for k in resp.headers}+ assert "x-snapshot-size" in {k.lower() for k in resp.headers}+ assert int(resp.headers["x-snapshot-size"]) == len(expected_bytes)+ assert resp.content == expected_bytes+++async def test_show_path_not_found_returns_404(client_with_resource):+ client, _ = client_with_resource+ commit = (await client.post("/api/v1/snapshot/commit", json={"message": "for 404"})).json()["result"]+ resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": commit["commit_oid"], "path": "viking://resources/does_not_exist.txt"},+ )+ assert resp.status_code == 404+ assert resp.json()["status"] == "error"+++# ---------------------------------------------------------------------------+# restore (apply) — forward-commit chain + reindex hook + concurrent-commit 409+# ---------------------------------------------------------------------------+++async def test_restore_apply_advances_head_with_forward_commit(client_with_resource_and_blob, service):+ """End-to-end restore (dry_run=False) over HTTP: verify forward-commit+ semantics — the new commit's parent is the previous HEAD, NOT the source+ commit, and the workspace bytes match the source.+ """+ from openviking.server.identity import RequestContext, Role+ from openviking_cli.session.user_id import UserIdentifier++ client, c1_oid, blob_uri, v1_bytes = client_with_resource_and_blob+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)++ # Overwrite the blob and commit a second snapshot (c2 becomes new HEAD).+ v2_bytes = b"v2 modified content\n"+ await service.viking_fs.write_file(blob_uri, v2_bytes, ctx=ctx)+ c2_resp = await client.post("/api/v1/snapshot/commit", json={"message": "v2"})+ assert c2_resp.status_code == 200, c2_resp.text+ c2 = c2_resp.json()["result"]+ assert c2["result"] == "created"+ c2_oid = c2["commit_oid"]++ # Apply restore back to c1 over the whole resources scope.+ restore_resp = await client.post(+ "/api/v1/snapshot/restore",+ json={+ "project_dir": "viking://resources",+ "source_commit": c1_oid,+ },+ )+ assert restore_resp.status_code == 200, restore_resp.text+ body = restore_resp.json()+ assert body["status"] == "ok"+ result = body["result"]+ assert result["result"] == "applied"+ assert result["source_commit"] == c1_oid+ assert result["parent_commit"] == c2_oid # forward-commit: parent = old HEAD+ new_oid = result["new_commit_oid"]+ assert new_oid not in (c1_oid, c2_oid)++ # HEAD must point at the new commit, whose parent[0] == c2 (NOT c1).+ head_resp = await client.get("/api/v1/snapshot/show", params={"target_ref": "main"})+ assert head_resp.status_code == 200+ head = head_resp.json()["result"]+ assert head["oid"] == new_oid+ assert head["parents"] == [c2_oid]++ # The blob in the restored commit must equal v1.+ show_resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": new_oid, "path": blob_uri},+ )+ assert show_resp.status_code == 200+ assert show_resp.content == v1_bytes+++async def test_restore_without_project_dir_restores_full_account_tree(client_with_resource_and_blob, service):+ from openviking.server.identity import RequestContext, Role+ from openviking_cli.session.user_id import UserIdentifier++ client, c1_oid, blob_uri, v1_bytes = client_with_resource_and_blob+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)+ extra_uri = "viking://resources/full_restore_new.txt"++ await service.viking_fs.write_file(blob_uri, b"v2 modified content\n", ctx=ctx)+ await service.viking_fs.write_file(extra_uri, b"new at v2\n", ctx=ctx)+ c2_resp = await client.post("/api/v1/snapshot/commit", json={"message": "v2 full restore setup"})+ assert c2_resp.status_code == 200, c2_resp.text+ c2_oid = c2_resp.json()["result"]["commit_oid"]++ restore_resp = await client.post(+ "/api/v1/snapshot/restore",+ json={"source_commit": c1_oid},+ )+ assert restore_resp.status_code == 200, restore_resp.text+ result = restore_resp.json()["result"]+ assert result["result"] == "applied"+ assert result["source_commit"] == c1_oid+ assert result["parent_commit"] == c2_oid+ assert blob_uri.removeprefix("viking://") in result["written_paths"]+ assert extra_uri.removeprefix("viking://") in result["deleted_paths"]++ show_resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": result["new_commit_oid"], "path": blob_uri},+ )+ assert show_resp.status_code == 200+ assert show_resp.content == v1_bytes++ missing_resp = await client.get(+ "/api/v1/snapshot/show",+ params={"target_ref": result["new_commit_oid"], "path": extra_uri},+ )+ assert missing_resp.status_code == 404+++async def test_restore_apply_triggers_reindex_hook(client_with_resource_and_blob, service, monkeypatch):+ """Verify the HTTP restore path actually invokes the vector-reindex+ scheduler — protects the chain router -> viking_fs.restore -> _schedule_vector_rebuild.+ """+ from openviking.server.identity import RequestContext, Role+ from openviking_cli.session.user_id import UserIdentifier+ import openviking.service.reindex_executor as reindex_mod++ client, c1_oid, blob_uri, _v1 = client_with_resource_and_blob+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)++ calls: list[str] = []++ class _SpyExecutor:+ async def execute(self, *, uri, mode, wait, ctx):+ calls.append(uri)+ return {"ok": True}++ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: _SpyExecutor())++ # Mutate, commit v2, then restore back to c1 — must produce a reindex call.+ await service.viking_fs.write_file(blob_uri, b"v2-bytes\n", ctx=ctx)+ await client.post("/api/v1/snapshot/commit", json={"message": "v2"})++ restore_resp = await client.post(+ "/api/v1/snapshot/restore",+ json={"project_dir": "viking://resources", "source_commit": c1_oid},+ )+ assert restore_resp.status_code == 200, restore_resp.text+ assert restore_resp.json()["result"]["result"] == "applied"++ # The restore reindex now runs in a tracked background task; poll a little+ # to let start() + the gathered rebuild coroutines flush.+ import asyncio+ for _ in range(100):+ if calls:+ break+ await asyncio.sleep(0.02)++ assert calls, "expected at least one reindex call after restore apply"+++async def test_restore_delete_removes_orphaned_vectors(client_with_resource_and_blob, service, monkeypatch):+ """Restoring to a revision that predates a file must purge that file's+ vectors, not merely skip them.++ ReindexExecutor only upserts from on-disk content and never deletes, so a+ file removed by the restore would otherwise leave orphaned vectors behind.+ viking_fs.restore must route deleted source paths to the executor's+ level-precise delete (DETAIL).+ """+ from openviking.server.identity import RequestContext, Role+ from openviking_cli.session.user_id import UserIdentifier+ import openviking.service.reindex_executor as reindex_mod++ client, c1_oid, _blob_uri, _v1 = client_with_resource_and_blob+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)++ deleted_calls: list[tuple] = []++ class _SpyExecutor:+ async def execute(self, *, uri, mode, wait, ctx):+ return {"ok": True}++ async def reindex_directory_marker(self, *, dir_uri, level, ctx):+ return None++ async def delete_uri_level(self, *, uri, level, ctx):+ deleted_calls.append((uri, int(level)))+ return 0++ monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: _SpyExecutor())++ # Add a brand-new file that does not exist at c1, then commit v2.+ new_uri = "viking://resources/restore_delete_fixture.txt"+ await service.viking_fs.write_file(new_uri, b"only-exists-at-v2\n", ctx=ctx)+ await client.post("/api/v1/snapshot/commit", json={"message": "v2 add file"})++ # Restore back to c1: the new file must be deleted, and its vectors purged.+ restore_resp = await client.post(+ "/api/v1/snapshot/restore",+ json={"project_dir": "viking://resources", "source_commit": c1_oid},+ )+ assert restore_resp.status_code == 200, restore_resp.text+ assert restore_resp.json()["result"]["result"] == "applied"++ import asyncio+ for _ in range(100):+ if (new_uri, 2) in deleted_calls:+ break+ await asyncio.sleep(0.02)++ assert (new_uri, 2) in deleted_calls, (+ f"deleted file's DETAIL vector must be purged; got {deleted_calls!r}"+ )++++async def test_restore_concurrent_commit_returns_409(client_with_resource_and_blob, service, monkeypatch):+ """Force the underlying git CAS swap to raise GitConcurrentCommitError+ and verify the HTTP layer maps it to 409 with CONFLICT code.+ """+ from openviking.pyagfs.exceptions import GitConcurrentCommitError++ client, c1_oid, _blob_uri, _v1 = client_with_resource_and_blob++ async def _raise_conflict(self, *, message=None, **kwargs):+ raise GitConcurrentCommitError("git ref refs/heads/main changed under us")++ from openviking.storage.viking_fs import VikingFS++ monkeypatch.setattr(VikingFS, "restore", _raise_conflict)++ resp = await client.post(+ "/api/v1/snapshot/restore",+ json={"project_dir": "viking://resources", "source_commit": c1_oid},+ )+ assert resp.status_code == 409, resp.text+ body = resp.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "CONFLICT"+++async def test_restore_partial_writeback_surfaces_structured_error(+ client_with_resource_and_blob, service, monkeypatch+):+ """When VikingFS.restore raises GitRestoreWritebackPartialError, the+ router must turn it into an OpenVikingError(code='RESTORE_WRITEBACK_PARTIAL')+ whose ``details`` carry the full payload (new_commit_oid, failed paths,+ task_id) — NOT a generic InternalError.+ """+ from openviking.pyagfs.exceptions import GitRestoreWritebackPartialError++ client, c1_oid, _blob_uri, _v1 = client_with_resource_and_blob++ async def _raise_partial(self, *, message=None, **kwargs):+ payload = {+ "new_commit_oid": "f" * 40,+ "source_commit": c1_oid,+ "parent_commit": "e" * 40,+ "written": 1,+ "deleted": 0,+ "unchanged": 0,+ "written_paths": ["resources/ok.md"],+ "deleted_paths": [],+ "failed_writes": [("resources/bad.md", "vfs write boom")],+ "failed_deletes": [],+ }+ exc = GitRestoreWritebackPartialError(+ "restore writeback partial: 1 write(s) and 0 delete(s) failed",+ payload=payload,+ )+ exc.task_id = "task-fixture-xyz"+ raise exc++ from openviking.storage.viking_fs import VikingFS++ monkeypatch.setattr(VikingFS, "restore", _raise_partial)++ resp = await client.post(+ "/api/v1/snapshot/restore",+ json={"project_dir": "viking://resources", "source_commit": c1_oid},+ )+ assert resp.status_code == 500, resp.text+ body = resp.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "RESTORE_WRITEBACK_PARTIAL"+ details = body["error"]["details"]+ assert details["new_commit_oid"] == "f" * 40+ assert details["task_id"] == "task-fixture-xyz"+ assert details["written_paths"] == ["resources/ok.md"]+ # failed_writes round-trips as list-of-list under JSON since to_dict+ # serialises the tuples that way.+ assert details["failed_writes"] == [["resources/bad.md", "vfs write boom"]]+++async def test_restore_rejects_unknown_field_per_pydantic_forbid(client_with_resource):+ """Pydantic ConfigDict(extra='forbid') on RestoreRequest must reject typo'd fields.++ The OpenViking error mapper rewrites FastAPI's default 422 into HTTP 400+ with code INVALID_ARGUMENT — that's the contract callers see.+ """+ client, _ = client_with_resource+ commit = (await client.post("/api/v1/snapshot/commit", json={"message": "v"})).json()["result"]+ resp = await client.post(+ "/api/v1/snapshot/restore",+ json={+ "project_dir": "viking://resources",+ "source_commit": commit["commit_oid"],+ "dryRun": True, # typo: should be dry_run+ },+ )+ assert resp.status_code == 400, resp.text+ body = resp.json()+ assert body["status"] == "error"+ assert body["error"]["code"] == "INVALID_ARGUMENT"+ # The offending field name must surface in the error so the user can fix it.+ assert "dryRun" in body["error"]["message"]diff --git a/tests/server/test_error_mapping.py b/tests/server/test_error_mapping.pyindex 3e1c78c63..7129cf60e 100644--- a/tests/server/test_error_mapping.py+++ b/tests/server/test_error_mapping.py@@ -3,8 +3,14 @@"""Focused tests for HTTP server exception-to-error mapping."""-from openviking.pyagfs.exceptions import AGFSClientError, AGFSHTTPError, AGFSIsADirectoryError+from openviking.pyagfs.exceptions import (+ AGFSClientError,+ AGFSHTTPError,+ AGFSIsADirectoryError,+ GitConcurrentCommitError,+)from openviking.server.error_mapping import map_exception+from openviking.server.models import ERROR_CODE_TO_HTTP_STATUSfrom openviking.storage.errors import LockAcquisitionError, ResourceBusyErrorfrom openviking_cli.exceptions import (FailedPreconditionError,@@ -198,3 +204,11 @@ def test_lock_acquisition_maps_to_structured_conflict():"conflict_type": "path_busy","retryable": True,}+++def test_git_concurrent_commit_maps_to_conflict():+ err = GitConcurrentCommitError("ref moved")+ mapped = map_exception(err)+ assert mapped is not None+ assert mapped.code == "CONFLICT"+ assert ERROR_CODE_TO_HTTP_STATUS.get(mapped.code) == 409diff --git a/tests/storage/test_viking_fs_git.py b/tests/storage/test_viking_fs_git.pynew file mode 100644index 000000000..81ed5674a--- /dev/null+++ b/tests/storage/test_viking_fs_git.py@@ -0,0 +1,17 @@+# tests/storage/test_viking_fs_git.py+import pytest++pytestmark = pytest.mark.asyncio++[email protected](reason="needs git-enabled VikingFS fixture")+async def test_show_blob_raw_returns_envelope(viking_fs_with_two_commits):+ """show_blob_raw must return the full {oid, size, bytes} dict, not strip it."""+ vfs, _account, commit_oid, sample_path, sample_bytes = viking_fs_with_two_commits++ raw = await vfs.show_blob_raw(commit_oid, path=sample_path)++ assert isinstance(raw, dict)+ assert raw["bytes"] == sample_bytes+ assert raw["size"] == len(sample_bytes)+ assert isinstance(raw["oid"], str) and len(raw["oid"]) == 40diff --git a/tests/unit/test_create_agfs_client_git.py b/tests/unit/test_create_agfs_client_git.pynew file mode 100644index 000000000..c13af0cf1--- /dev/null+++ b/tests/unit/test_create_agfs_client_git.py@@ -0,0 +1,118 @@+"""Tests for git wiring in create_agfs_client.++Verifies that when GitConfig.enabled is True, create_agfs_client builds an+in-memory git config dict and injects it into the binding ``config`` under the+``git`` key (no file is written to disk). When git is disabled (or git_config is+None), no ``git`` section is added to the binding config.+"""+from types import SimpleNamespace++import pytest++from openviking_cli.utils.config import GitConfig, GitLocalConfig+from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client+++class _FakeAgfsConfig:+ """Minimal stand-in for StorageConfig.agfs — only what mount + binding need."""++ def __init__(self, path):+ self.path = str(path)+ self.backend = "local"+ self.s3 = None+ # cache section consumed by RagfsBindingConfig.to_binding_dict()+ self.cache = SimpleNamespace(model_dump=lambda **kwargs: {})+ # queuefs default+ self.queuefs = SimpleNamespace(+ backend="sqlite", recover_stale_sec=0, busy_timeout_ms=5000, db_path=None+ )+++def agfs_config(tmp_path):+ return _FakeAgfsConfig(tmp_path / "data")+++def fake_binding(monkeypatch):+ """Stub out RAGFSBindingClient to capture constructor kwargs."""+ instances = []++ class _FakeClient:+ def __init__(self, *args, **kwargs):+ self.args = args+ self.kwargs = kwargs+ instances.append(self)++ def mount(self, *a, **k):+ pass++ def unmount(self, *a, **k):+ pass++ from openviking import pyagfs as pyagfs_mod+ monkeypatch.setattr(+ pyagfs_mod, "get_binding_client", lambda: (_FakeClient, None)+ )+ return instances+++def test_git_disabled_omits_git_section(agfs_config, fake_binding):+ """git_config=None → binding config has no 'git' section."""+ create_agfs_client(RagfsBindingConfig(agfs=agfs_config))+ assert len(fake_binding) == 1+ assert "git" not in fake_binding[0].kwargs.get("config", {})+ assert "git_config_path" not in fake_binding[0].kwargs+++def test_git_disabled_explicit_omits_git_section(agfs_config, fake_binding):+ """An explicitly-disabled GitConfig is equivalent to None."""+ cfg = GitConfig(enabled=False)+ create_agfs_client(RagfsBindingConfig(agfs=agfs_config), git_config=cfg)+ assert "git" not in fake_binding[0].kwargs.get("config", {})+++def test_git_enabled_injects_git_dict_into_config(agfs_config, fake_binding, tmp_path):+ """enabled=True → injects a 'git' dict into the binding config, no file written."""+ cfg = GitConfig(+ enabled=True,+ backend="local",+ default_branch="main",+ author_name="viking-bot",+ author_email="[email protected]",+ local=GitLocalConfig(base_dir=str(tmp_path / "git")),+ )+ create_agfs_client(RagfsBindingConfig(agfs=agfs_config), git_config=cfg)++ kwargs = fake_binding[0].kwargs+ assert "git_config_path" not in kwargs+ git = kwargs["config"]["git"]+ assert git["enabled"] is True+ assert git["backend"] == "local"+ assert git["author_name"] == "viking-bot"+ assert git["local"]["base_dir"] == str(tmp_path / "git")+++def test_git_enabled_with_empty_base_dir_defaults_to_storage_git(agfs_config, fake_binding):+ """When local.base_dir is empty, the git dict should fill it with {storage_path}/.ovgit."""+ from pathlib import Path++ cfg = GitConfig(enabled=True, local=GitLocalConfig(base_dir=""))+ create_agfs_client(RagfsBindingConfig(agfs=agfs_config), git_config=cfg)+ git = fake_binding[0].kwargs["config"]["git"]+ expected = str(Path(agfs_config.path).resolve() / ".ovgit")+ assert git["local"]["base_dir"] == expected+++def test_git_enabled_preserves_special_chars_in_strings(agfs_config, fake_binding, tmp_path):+ """Strings with backslashes / quotes are preserved verbatim in the dict."""+ cfg = GitConfig(+ enabled=True,+ author_name='He said "hi"',+ author_email='a\\[email protected]',+ local=GitLocalConfig(base_dir=str(tmp_path / "git")),+ )+ create_agfs_client(RagfsBindingConfig(agfs=agfs_config), git_config=cfg)+ git = fake_binding[0].kwargs["config"]["git"]+ assert git["author_name"] == 'He said "hi"'+ assert git["author_email"] == 'a\\[email protected]'diff --git a/tests/unit/test_fs_service_git_forwarders.py b/tests/unit/test_fs_service_git_forwarders.pynew file mode 100644index 000000000..06afc2023--- /dev/null+++ b/tests/unit/test_fs_service_git_forwarders.py@@ -0,0 +1,144 @@+"""Tests for FSService git forwarder methods.++These tests verify FSService.{commit, restore, show, log} pass the right+args to VikingFS. They don't exercise real git — that's covered by+tests/agfs/test_viking_fs_git.py.+"""+from unittest.mock import AsyncMock, MagicMock++import pytest++from openviking.server.identity import RequestContext, Role+from openviking.service.fs_service import FSService+from openviking_cli.exceptions import NotInitializedError+from openviking_cli.session.user_id import UserIdentifier+++def _ctx():+ return RequestContext(+ user=UserIdentifier(account_id="acc", user_id="user"),+ role=Role.ROOT,+ )+++def viking_fs_mock():+ m = MagicMock()+ m.commit = AsyncMock(return_value={"result": "created", "commit_oid": "a" * 40, "changed": 1})+ m.restore = AsyncMock(return_value={"result": "applied", "commit_oid": "b" * 40})+ m.show = AsyncMock(return_value={"oid": "c" * 40, "message": "m", "parents": []})+ m.log = AsyncMock(return_value=[{"oid": "c" * 40, "message": "m"}])+ return m+++def svc(viking_fs_mock):+ s = FSService(viking_fs=viking_fs_mock)+ return s+++async def test_commit_forwards_all_kwargs(svc, viking_fs_mock):+ ctx = _ctx()+ out = await svc.commit(+ message="snapshot",+ ctx=ctx,+ paths=["viking://resources/a.md"],+ branch="main",+ author_name="me",+ author_email="me@x",+ )+ viking_fs_mock.commit.assert_awaited_once_with(+ message="snapshot",+ paths=["viking://resources/a.md"],+ branch="main",+ author_name="me",+ author_email="me@x",+ ctx=ctx,+ )+ assert out["commit_oid"] == "a" * 40+++async def test_commit_defaults_paths_to_none(svc, viking_fs_mock):+ ctx = _ctx()+ await svc.commit(message="m", ctx=ctx)+ kwargs = viking_fs_mock.commit.await_args.kwargs+ assert kwargs["paths"] is None+ assert kwargs["branch"] == "main"+ assert kwargs["author_name"] is None+ assert kwargs["author_email"] is None+++async def test_restore_forwards_all_kwargs(svc, viking_fs_mock):+ ctx = _ctx()+ out = await svc.restore(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ ctx=ctx,+ branch="main",+ dry_run=True,+ message="rolling back",+ author_name="me",+ author_email="me@x",+ )+ viking_fs_mock.restore.assert_awaited_once_with(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ branch="main",+ dry_run=True,+ message="rolling back",+ author_name="me",+ author_email="me@x",+ ctx=ctx,+ )+ assert out["result"] == "applied"+++async def test_show_metadata_without_path(svc, viking_fs_mock):+ ctx = _ctx()+ out = await svc.show("main", ctx=ctx)+ viking_fs_mock.show.assert_awaited_once_with("main", path=None, ctx=ctx)+ assert out["oid"] == "c" * 40+++async def test_show_with_path_validated(svc, viking_fs_mock):+ ctx = _ctx()+ viking_fs_mock.show = AsyncMock(return_value=b"hello")+ out = await svc.show("main", ctx=ctx, path="viking://resources/a.md")+ viking_fs_mock.show.assert_awaited_once_with(+ "main", path="viking://resources/a.md", ctx=ctx+ )+ assert out == b"hello"+++async def test_log_defaults(svc, viking_fs_mock):+ ctx = _ctx()+ out = await svc.log(ctx=ctx)+ viking_fs_mock.log.assert_awaited_once_with(branch="main", limit=20, ctx=ctx)+ assert len(out) == 1+++async def test_log_with_overrides(svc, viking_fs_mock):+ ctx = _ctx()+ await svc.log(ctx=ctx, branch="dev", limit=5)+ viking_fs_mock.log.assert_awaited_once_with(branch="dev", limit=5, ctx=ctx)+++async def test_methods_raise_when_not_initialized():+ svc = FSService() # no viking_fs set+ ctx = _ctx()+ with pytest.raises(NotInitializedError):+ await svc.commit(message="m", ctx=ctx)+ with pytest.raises(NotInitializedError):+ await svc.restore(project_dir="viking://x", source_commit="a", ctx=ctx)+ with pytest.raises(NotInitializedError):+ await svc.show("main", ctx=ctx)+ with pytest.raises(NotInitializedError):+ await svc.log(ctx=ctx)diff --git a/tests/unit/test_git_config.py b/tests/unit/test_git_config.pynew file mode 100644index 000000000..0a74e9e7c--- /dev/null+++ b/tests/unit/test_git_config.py@@ -0,0 +1,277 @@+"""Unit tests for GitConfig pydantic model."""+import json+from pathlib import Path++import pytest+from pydantic import ValidationError++from openviking_cli.utils.config import (+ GitConfig,+ GitLocalConfig,+ GitS3Config,+ OpenVikingConfig,+)+from openviking.utils.agfs_utils import _build_git_config_dict+++class TestGitConfigDefaults:+ def test_enabled_by_default(self):+ cfg = GitConfig()+ assert cfg.enabled is True+ assert cfg.backend == "local"+ assert cfg.default_branch == "main"+ assert cfg.author_name == "viking-bot"+ assert cfg.author_email == "[email protected]"++ def test_local_subconfig_defaults(self):+ cfg = GitConfig()+ assert isinstance(cfg.local, GitLocalConfig)+ assert cfg.local.base_dir == ""+++class TestGitConfigValidation:+ def test_invalid_backend_rejected(self):+ with pytest.raises(ValidationError):+ GitConfig(backend="ftp")++ def test_unknown_field_rejected(self):+ with pytest.raises(ValidationError):+ GitConfig(unknown_thing=True)++ def test_enabled_with_local_backend_ok(self):+ cfg = GitConfig(enabled=True, backend="local", local=GitLocalConfig(base_dir="/tmp/git"))+ assert cfg.enabled is True+ assert cfg.local.base_dir == "/tmp/git"+++class TestGitConfigOnOpenVikingConfig:+ def test_open_viking_config_has_git_field_with_default(self):+ cfg = OpenVikingConfig(storage={"workspace": "/tmp/x"})+ assert isinstance(cfg.git, GitConfig)+ assert cfg.git.enabled is True+ assert cfg.git.backend == "local"+ assert isinstance(cfg.git.local, GitLocalConfig)++ def test_open_viking_config_accepts_git_section(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x"},+ git={+ "enabled": True,+ "backend": "local",+ "local": {"base_dir": "/tmp/g"},+ },+ )+ assert cfg.git.enabled is True+ assert cfg.git.local.base_dir == "/tmp/g"++ def test_git_config_round_trip_via_config_file(self, tmp_path):+ """Round-trip the new `git` section through the runtime JSON file loader."""+ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfigSingleton,+ )++ cfg_dict = {+ "storage": {"workspace": str(tmp_path / "data")},+ "git": {+ "enabled": True,+ "backend": "local",+ "default_branch": "main",+ "author_name": "viking-bot",+ "author_email": "[email protected]",+ "local": {"base_dir": str(tmp_path / "git")},+ },+ }+ cfg_path = tmp_path / "ov.conf"+ cfg_path.write_text(json.dumps(cfg_dict))++ cfg = OpenVikingConfigSingleton._load_from_file(str(cfg_path))++ assert cfg.git.enabled is True+ assert cfg.git.local.base_dir == str(tmp_path / "git")+++class TestGitInheritsFromAgfs:+ """git section inherits unset defaults from storage.agfs."""++ FULL_S3 = {+ "bucket": "B",+ "region": "R",+ "endpoint": "E",+ "access_key": "AK",+ "secret_key": "SK",+ }++ def test_no_git_section_local_agfs(self):+ cfg = OpenVikingConfig(storage={"workspace": "/tmp/x"})+ assert cfg.git.enabled is True+ assert cfg.git.backend == "local"+ assert cfg.git.s3 is None++ def test_backend_inherits_s3_from_agfs(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x", "agfs": {"backend": "s3", "s3": self.FULL_S3}}+ )+ assert cfg.git.backend == "s3"+ assert cfg.git.s3.bucket == "B"+ assert cfg.git.s3.region == "R"+ assert cfg.git.s3.endpoint == "E"+ assert cfg.git.s3.access_key == "AK"+ assert cfg.git.s3.secret_key == "SK"++ def test_memory_agfs_maps_to_local(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x", "agfs": {"backend": "memory"}}+ )+ assert cfg.git.backend == "local"++ def test_explicit_git_backend_overrides_inheritance(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x", "agfs": {"backend": "s3", "s3": self.FULL_S3}},+ git={"backend": "local"},+ )+ assert cfg.git.backend == "local"+ assert cfg.git.s3 is None++ def test_explicit_git_s3_field_overrides_only_that_field(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x", "agfs": {"backend": "s3", "s3": self.FULL_S3}},+ git={"s3": {"bucket": "GB"}},+ )+ assert cfg.git.s3.bucket == "GB"+ # remaining fields inherited from agfs.s3+ assert cfg.git.s3.region == "R"+ assert cfg.git.s3.endpoint == "E"+ assert cfg.git.s3.access_key == "AK"+ assert cfg.git.s3.secret_key == "SK"++ def test_disabled_git_still_inherits_backend(self):+ cfg = OpenVikingConfig(+ storage={"workspace": "/tmp/x", "agfs": {"backend": "s3", "s3": self.FULL_S3}},+ git={"enabled": False},+ )+ assert cfg.git.enabled is False+ assert cfg.git.backend == "s3"+++class TestGitS3ConfigParsing:+ """A5.1 — parsing of the s3 backend config."""++ def test_s3_config_defaults(self):+ s3 = GitS3Config()+ assert s3.bucket == ""+ assert s3.region == "us-east-1"+ assert s3.prefix == ".ovgit"+ assert s3.endpoint == ""+ assert s3.access_key is None+ assert s3.secret_key is None+ assert s3.cas_mode == "native"+ assert s3.use_path_style is True++ def test_backend_s3_with_s3_section_ok(self):+ cfg = GitConfig(+ enabled=True,+ backend="s3",+ s3=GitS3Config(bucket="b", region="cn-beijing"),+ )+ assert cfg.backend == "s3"+ assert cfg.s3.bucket == "b"+ assert cfg.s3.region == "cn-beijing"++ def test_enabled_backend_s3_without_s3_section_rejected(self):+ with pytest.raises(ValidationError):+ GitConfig(enabled=True, backend="s3", s3=None)++ def test_enabled_backend_s3_missing_bucket_rejected(self):+ with pytest.raises(ValidationError):+ GitConfig(enabled=True, backend="s3", s3=GitS3Config(region="cn-beijing"))++ def test_enabled_backend_s3_missing_region_rejected(self):+ # region has a non-empty default, so explicitly blank it to trigger the check.+ with pytest.raises(ValidationError):+ GitConfig(+ enabled=True,+ backend="s3",+ s3=GitS3Config(bucket="b", region=""),+ )++ def test_disabled_backend_s3_skips_validation(self):+ # When git is disabled the s3 section is not required.+ cfg = GitConfig(enabled=False, backend="s3", s3=None)+ assert cfg.s3 is None++ def test_s3_unknown_field_rejected(self):+ with pytest.raises(ValidationError):+ GitS3Config(bucket="b", region="r", unknown="x")++ def test_invalid_cas_mode_rejected(self):+ with pytest.raises(ValidationError):+ GitS3Config(cas_mode="invalid")++ def test_redis_lock_cas_mode_rejected(self):+ with pytest.raises(ValidationError):+ GitS3Config(cas_mode="redis_lock")+++class TestBuildGitConfigDictS3:+ """A5.2 — _build_git_config_dict output for the s3 backend."""++ def _build_s3(self, **s3_kwargs):+ s3_defaults = {"bucket": "my-bucket", "region": "cn-beijing"}+ s3_defaults.update(s3_kwargs)+ cfg = GitConfig(enabled=True, backend="s3", s3=GitS3Config(**s3_defaults))+ return _build_git_config_dict(cfg, Path("/tmp/storage"))++ def test_builds_header_and_s3_section(self):+ out = self._build_s3()+ assert out["backend"] == "s3"+ assert "s3" in out+ assert "local" not in out++ def test_builds_required_s3_keys(self):+ out = self._build_s3(prefix="gitobj", endpoint="https://tos.example.com")+ s3 = out["s3"]+ assert s3["bucket"] == "my-bucket"+ assert s3["region"] == "cn-beijing"+ assert s3["prefix"] == "gitobj"+ assert s3["endpoint"] == "https://tos.example.com"+ assert s3["cas_mode"] == "native"++ def test_use_path_style_is_bool(self):+ out_true = self._build_s3(use_path_style=True)+ assert out_true["s3"]["use_path_style"] is True+ out_false = self._build_s3(use_path_style=False)+ assert out_false["s3"]["use_path_style"] is False++ def test_credentials_emitted_when_present(self):+ out = self._build_s3(access_key="AK", secret_key="SK")+ assert out["s3"]["access_key"] == "AK"+ assert out["s3"]["secret_key"] == "SK"++ def test_credentials_omitted_when_empty(self):+ out = self._build_s3()+ assert "access_key" not in out["s3"]+ assert "secret_key" not in out["s3"]++ def test_missing_s3_section_raises(self):+ # Build a disabled config (skips model validation) then force s3=None to+ # exercise the builder's own guard.+ cfg = GitConfig(enabled=False, backend="s3", s3=None)+ with pytest.raises(ValueError):+ _build_git_config_dict(cfg, Path("/tmp/storage"))+++class TestBuildGitConfigDictLocal:+ """A5.3 — regression: local backend still builds only a 'local' section."""++ def test_local_builds_local_section_only(self):+ cfg = GitConfig(enabled=True, backend="local", local=GitLocalConfig(base_dir="/tmp/g"))+ out = _build_git_config_dict(cfg, Path("/tmp/storage"))+ assert out["backend"] == "local"+ assert "local" in out+ assert "s3" not in out+ assert out["local"]["base_dir"] == "/tmp/g"++ def test_local_base_dir_defaults_to_storage_git(self):+ cfg = GitConfig(enabled=True, backend="local")+ out = _build_git_config_dict(cfg, Path("/tmp/storage"))+ assert out["local"]["base_dir"] == str(Path("/tmp/storage") / ".ovgit")diff --git a/tests/unit/test_local_client_git.py b/tests/unit/test_local_client_git.pynew file mode 100644index 000000000..d4105f560--- /dev/null+++ b/tests/unit/test_local_client_git.py@@ -0,0 +1,133 @@+"""Tests for LocalClient git version control methods.++Verifies that LocalClient.{git_commit, git_restore, git_show, git_log}+forward the right kwargs to FSService.{commit, restore, show, log}.+"""+from unittest.mock import AsyncMock, MagicMock++import pytest++from openviking.client.local import LocalClient+from openviking.server.identity import RequestContext, Role+from openviking_cli.session.user_id import UserIdentifier+++def mock_fs():+ m = MagicMock()+ m.commit = AsyncMock(return_value={"result": "created", "commit_oid": "a" * 40})+ m.restore = AsyncMock(return_value={"result": "applied", "commit_oid": "b" * 40})+ m.show = AsyncMock(return_value={"oid": "c" * 40, "message": "m", "parents": []})+ m.log = AsyncMock(return_value=[{"oid": "c" * 40, "message": "m"}])+ return m+++def local_client(mock_fs):+ """Build a LocalClient with a mocked FSService, bypassing __init__."""+ ctx = RequestContext(+ user=UserIdentifier(account_id="acc", user_id="u"),+ role=Role.ROOT,+ )+ client = object.__new__(LocalClient)+ client._service = MagicMock()+ client._service.fs = mock_fs+ client._ctx = ctx+ return client+++async def test_commit_forwards_kwargs(local_client, mock_fs):+ out = await local_client.git_commit(+ message="snapshot",+ paths=["viking://resources/a.md"],+ branch="main",+ author_name="me",+ author_email="me@x",+ )+ mock_fs.commit.assert_awaited_once_with(+ message="snapshot",+ paths=["viking://resources/a.md"],+ branch="main",+ author_name="me",+ author_email="me@x",+ ctx=local_client._ctx,+ )+ assert out["commit_oid"] == "a" * 40+++async def test_commit_defaults(local_client, mock_fs):+ await local_client.git_commit(message="m")+ kwargs = mock_fs.commit.await_args.kwargs+ assert kwargs["paths"] is None+ assert kwargs["branch"] == "main"+ assert kwargs["author_name"] is None+ assert kwargs["author_email"] is None+++async def test_restore_forwards_kwargs(local_client, mock_fs):+ out = await local_client.git_restore(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ branch="main",+ dry_run=True,+ message="rollback",+ author_name="me",+ author_email="me@x",+ )+ mock_fs.restore.assert_awaited_once_with(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ branch="main",+ dry_run=True,+ message="rollback",+ author_name="me",+ author_email="me@x",+ ctx=local_client._ctx,+ )+ assert out["result"] == "applied"+++async def test_restore_defaults_project_dir_none(local_client, mock_fs):+ await local_client.git_restore(source_commit="d" * 40)+ mock_fs.restore.assert_awaited_once_with(+ project_dir=None,+ source_commit="d" * 40,+ branch="main",+ dry_run=False,+ message=None,+ author_name=None,+ author_email=None,+ ctx=local_client._ctx,+ )+++async def test_show_metadata(local_client, mock_fs):+ out = await local_client.git_show("main")+ mock_fs.show.assert_awaited_once_with("main", path=None, ctx=local_client._ctx)+ assert out["oid"] == "c" * 40+++async def test_show_with_path(local_client, mock_fs):+ mock_fs.show = AsyncMock(return_value=b"blob data")+ out = await local_client.git_show("main", path="viking://resources/a.md")+ mock_fs.show.assert_awaited_once_with("main", path="viking://resources/a.md", ctx=local_client._ctx)+ assert out == b"blob data"+++async def test_log_defaults(local_client, mock_fs):+ out = await local_client.git_log()+ mock_fs.log.assert_awaited_once_with(branch="main", limit=20, ctx=local_client._ctx)+ assert len(out) == 1+++async def test_log_overrides(local_client, mock_fs):+ await local_client.git_log(branch="dev", limit=5)+ mock_fs.log.assert_awaited_once_with(branch="dev", limit=5, ctx=local_client._ctx)diff --git a/tests/unit/test_snapshot_namespace.py b/tests/unit/test_snapshot_namespace.pynew file mode 100644index 000000000..e24c648e0--- /dev/null+++ b/tests/unit/test_snapshot_namespace.py@@ -0,0 +1,176 @@+"""Unit tests for AsyncSnapshotNamespace and SyncSnapshotNamespace.++These tests verify the namespace classes forward to the underlying+client's git_* methods correctly. They don't exercise real git.+"""+from unittest.mock import AsyncMock, MagicMock++import pytest++from openviking.snapshot_namespace import AsyncSnapshotNamespace, SyncSnapshotNamespace+++def fake_async_client():+ """A fake AsyncOpenViking with a mocked _client (BaseClient)."""+ parent = MagicMock()+ parent._ensure_initialized = AsyncMock(return_value=None)+ parent._client = MagicMock()+ parent._client.git_commit = AsyncMock(return_value={"result": "created", "commit_oid": "a" * 40})+ parent._client.git_restore = AsyncMock(return_value={"result": "applied", "commit_oid": "b" * 40})+ parent._client.git_show = AsyncMock(return_value={"oid": "c" * 40, "parents": []})+ parent._client.git_log = AsyncMock(return_value=[{"oid": "c" * 40}])+ return parent+++def async_ns(fake_async_client):+ return AsyncSnapshotNamespace(fake_async_client)+++# -------- AsyncSnapshotNamespace --------+++async def test_async_commit_forwards(async_ns, fake_async_client):+ out = await async_ns.commit(message="m", paths=["viking://x/a"], branch="dev",+ author_name="me", author_email="me@x")+ fake_async_client._ensure_initialized.assert_awaited()+ fake_async_client._client.git_commit.assert_awaited_once_with(+ message="m", paths=["viking://x/a"], branch="dev",+ author_name="me", author_email="me@x",+ )+ assert out["commit_oid"] == "a" * 40+++async def test_async_commit_defaults(async_ns, fake_async_client):+ await async_ns.commit(message="m")+ kwargs = fake_async_client._client.git_commit.await_args.kwargs+ assert kwargs == {+ "message": "m", "paths": None, "branch": "main",+ "author_name": None, "author_email": None,+ }+++async def test_async_restore_forwards(async_ns, fake_async_client):+ out = await async_ns.restore(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ dry_run=True,+ message="rollback",+ )+ fake_async_client._client.git_restore.assert_awaited_once_with(+ project_dir="viking://resources/proj",+ source_commit="d" * 40,+ branch="main",+ dry_run=True,+ message="rollback",+ author_name=None,+ author_email=None,+ )+ assert out["result"] == "applied"+++async def test_async_restore_defaults_project_dir_none(async_ns, fake_async_client):+ await async_ns.restore(source_commit="d" * 40)+ fake_async_client._client.git_restore.assert_awaited_once_with(+ project_dir=None,+ source_commit="d" * 40,+ branch="main",+ dry_run=False,+ message=None,+ author_name=None,+ author_email=None,+ )+++async def test_async_show_no_path(async_ns, fake_async_client):+ out = await async_ns.show("main")+ fake_async_client._client.git_show.assert_awaited_once_with("main", path=None)+ assert out["oid"] == "c" * 40+++async def test_async_show_with_path(async_ns, fake_async_client):+ fake_async_client._client.git_show = AsyncMock(return_value=b"data")+ out = await async_ns.show("main", path="viking://x/a")+ fake_async_client._client.git_show.assert_awaited_once_with("main", path="viking://x/a")+ assert out == b"data"+++async def test_async_log_defaults(async_ns, fake_async_client):+ out = await async_ns.log()+ fake_async_client._client.git_log.assert_awaited_once_with(branch="main", limit=20)+ assert len(out) == 1+++async def test_async_log_overrides(async_ns, fake_async_client):+ await async_ns.log(branch="dev", limit=5)+ fake_async_client._client.git_log.assert_awaited_once_with(branch="dev", limit=5)+++async def test_async_ensures_initialized_before_every_call(async_ns, fake_async_client):+ await async_ns.commit(message="m")+ await async_ns.show("main")+ await async_ns.log()+ assert fake_async_client._ensure_initialized.await_count == 3+++# -------- SyncSnapshotNamespace --------+++def test_sync_namespace_delegates_through_async(monkeypatch):+ """SyncSnapshotNamespace.commit() runs the async equivalent via run_async."""+ # Build a fake SyncOpenViking exposing an async_client with a snapshot namespace.+ sync_parent = MagicMock()+ inner_async_ns = MagicMock()+ inner_async_ns.commit = AsyncMock(return_value={"commit_oid": "z" * 40})+ inner_async_ns.restore = AsyncMock(return_value={"result": "applied"})+ inner_async_ns.show = AsyncMock(return_value=b"blob")+ inner_async_ns.log = AsyncMock(return_value=[])+ sync_parent._async_client.snapshot = inner_async_ns++ sync_ns = SyncSnapshotNamespace(sync_parent)++ out = sync_ns.commit(message="m")+ assert out["commit_oid"] == "z" * 40+ inner_async_ns.commit.assert_awaited_once_with(+ message="m", paths=None, branch="main",+ author_name=None, author_email=None,+ )++ sync_ns.show("main", path="viking://x/a")+ inner_async_ns.show.assert_awaited_once_with("main", path="viking://x/a")++ sync_ns.log(branch="dev", limit=3)+ inner_async_ns.log.assert_awaited_once_with(branch="dev", limit=3)+++def test_async_client_snapshot_property_is_lazy_and_cached():+ """Accessing .snapshot twice returns the same instance and doesn't construct early."""+ from openviking.async_client import AsyncOpenViking+ # Avoid real construction by faking the singleton.+ inst = object.__new__(AsyncOpenViking)+ # Patch the lazy attribute machinery+ assert not hasattr(inst, "_snapshot")+ ns1 = inst.snapshot+ assert isinstance(ns1, AsyncSnapshotNamespace)+ ns2 = inst.snapshot+ assert ns1 is ns2+++def test_sync_client_snapshot_property_is_lazy_and_cached():+ from openviking.sync_client import SyncOpenViking+ inst = object.__new__(SyncOpenViking)+ assert not hasattr(inst, "_snapshot")+ ns1 = inst.snapshot+ assert isinstance(ns1, SyncSnapshotNamespace)+ ns2 = inst.snapshot+ assert ns1 is ns2