Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(ovpack): add v2 manifest and backup restore (#1927)

Qin Haojiee648b2679c22
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 9e7da0819..e72cb80de 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -638,12 +638,14 @@ impl HttpClient {
// ============ Pack Methods ============
- pub async fn export_ovpack(&self, uri: &str, to: &str) -> Result<String> {
- let body = serde_json::json!({
- "uri": uri,
- });
-
- let url = format!("{}/api/v1/pack/export", self.base.base_url);
+ async fn download_pack(
+ &self,
+ endpoint: &str,
+ body: serde_json::Value,
+ to: &str,
+ default_name: &str,
+ ) -> Result<String> {
+ let url = format!("{}{}", self.base.base_url, endpoint);
let response = self
.base
.http
@@ -689,12 +691,7 @@ impl HttpClient {
let to_path = Path::new(to);
let final_path = if to_path.is_dir() {
- let base_name = uri
- .trim_end_matches('/')
- .split('/')
- .last()
- .unwrap_or("export");
- to_path.join(format!("{}.ovpack", base_name))
+ to_path.join(format!("{}.ovpack", default_name))
} else if !to.ends_with(".ovpack") {
Path::new(&format!("{}.ovpack", to)).to_path_buf()
} else {
@@ -710,12 +707,34 @@ impl HttpClient {
Ok(final_path.to_string_lossy().to_string())
}
+ pub async fn export_ovpack(&self, uri: &str, to: &str) -> Result<String> {
+ let body = serde_json::json!({
+ "uri": uri,
+ });
+ let base_name = uri
+ .trim_end_matches('/')
+ .split('/')
+ .last()
+ .unwrap_or("export");
+ self.download_pack("/api/v1/pack/export", body, to, base_name)
+ .await
+ }
+
+ pub async fn backup_ovpack(&self, to: &str) -> Result<String> {
+ self.download_pack(
+ "/api/v1/pack/backup",
+ serde_json::json!({}),
+ to,
+ "openviking-backup",
+ )
+ .await
+ }
+
pub async fn import_ovpack(
&self,
file_path: &str,
parent: &str,
- force: bool,
- vectorize: bool,
+ on_conflict: Option<&str>,
) -> Result<serde_json::Value> {
let file_path_obj = Path::new(file_path);
@@ -730,15 +749,41 @@ impl HttpClient {
}
let temp_file_id = self.upload_temp_file(file_path_obj).await?;
+ let conflict_policy = on_conflict.unwrap_or("fail");
let body = serde_json::json!({
"temp_file_id": temp_file_id,
"parent": parent,
- "force": force,
- "vectorize": vectorize,
+ "on_conflict": conflict_policy,
});
self.post("/api/v1/pack/import", &body).await
}
+ pub async fn restore_ovpack(
+ &self,
+ file_path: &str,
+ on_conflict: Option<&str>,
+ ) -> Result<serde_json::Value> {
+ let file_path_obj = Path::new(file_path);
+
+ if !file_path_obj.exists() {
+ return Err(Error::Client(format!(
+ "Local ovpack file not found: {}",
+ file_path
+ )));
+ }
+ if !file_path_obj.is_file() {
+ return Err(Error::Client(format!("Path is not a file: {}", file_path)));
+ }
+
+ let temp_file_id = self.upload_temp_file(file_path_obj).await?;
+ let conflict_policy = on_conflict.unwrap_or("fail");
+ let body = serde_json::json!({
+ "temp_file_id": temp_file_id,
+ "on_conflict": conflict_policy,
+ });
+ self.post("/api/v1/pack/restore", &body).await
+ }
+
// ============ Admin Methods ============
pub async fn admin_create_account(
diff --git a/crates/ov_cli/src/commands/pack.rs b/crates/ov_cli/src/commands/pack.rs
index 54341659a..5ab409b9f 100644
--- a/crates/ov_cli/src/commands/pack.rs
+++ b/crates/ov_cli/src/commands/pack.rs
@@ -21,19 +21,46 @@ pub async fn export(
Ok(())
}
+pub async fn backup(
+ client: &HttpClient,
+ to: &str,
+ format: OutputFormat,
+ compact: bool,
+) -> Result<()> {
+ let file_path = client.backup_ovpack(to).await?;
+
+ let result = serde_json::json!({
+ "file": file_path,
+ "message": format!("Successfully backed up to {}", file_path)
+ });
+
+ output_success(&result, format, compact);
+ Ok(())
+}
+
pub async fn import(
client: &HttpClient,
file_path: &str,
target: &str,
- force: bool,
- no_vectorize: bool,
+ on_conflict: Option<&str>,
format: OutputFormat,
compact: bool,
) -> Result<()> {
- let vectorize = !no_vectorize;
let result = client
- .import_ovpack(file_path, target, force, vectorize)
+ .import_ovpack(file_path, target, on_conflict)
.await?;
output_success(&result, format, compact);
Ok(())
}
+
+pub async fn restore(
+ client: &HttpClient,
+ file_path: &str,
+ on_conflict: Option<&str>,
+ format: OutputFormat,
+ compact: bool,
+) -> Result<()> {
+ let result = client.restore_ovpack(file_path, on_conflict).await?;
+ output_success(&result, format, compact);
+ Ok(())
+}
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 2c44a0ea0..10ff8a7db 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -165,11 +165,15 @@ pub async fn handle_export(uri: String, to: String, ctx: CliContext) -> Result<(
commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact).await
}
+pub async fn handle_backup(to: String, ctx: CliContext) -> Result<()> {
+ let client = ctx.get_client();
+ commands::pack::backup(&client, &to, ctx.output_format, ctx.compact).await
+}
+
pub async fn handle_import(
file_path: String,
target_uri: String,
- force: bool,
- no_vectorize: bool,
+ on_conflict: Option<String>,
ctx: CliContext,
) -> Result<()> {
let client = ctx.get_client();
@@ -177,8 +181,23 @@ pub async fn handle_import(
&client,
&file_path,
&target_uri,
- force,
- no_vectorize,
+ on_conflict.as_deref(),
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
+}
+
+pub async fn handle_restore(
+ file_path: String,
+ on_conflict: Option<String>,
+ ctx: CliContext,
+) -> Result<()> {
+ let client = ctx.get_client();
+ commands::pack::restore(
+ &client,
+ &file_path,
+ on_conflict.as_deref(),
ctx.output_format,
ctx.compact,
)
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index c291f3bfa..1a2f54b99 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -494,18 +494,28 @@ enum Commands {
/// Output .ovpack file path
to: String,
},
+ /// [Data] Back up public OpenViking scopes as a restore-only .ovpack
+ Backup {
+ /// Output .ovpack file path
+ to: String,
+ },
/// [Data] Import .ovpack into target URI
Import {
/// Input .ovpack file path
file_path: String,
/// Target parent URI
target_uri: String,
- /// Overwrite when conflicts exist
- #[arg(long)]
- force: bool,
- /// Disable vectorization after import
- #[arg(long)]
- no_vectorize: bool,
+ /// Conflict policy: fail, overwrite, or skip
+ #[arg(long, value_parser = ["fail", "overwrite", "skip"])]
+ on_conflict: Option<String>,
+ },
+ /// [Data] Restore a backup .ovpack to original public scope roots
+ Restore {
+ /// Input backup .ovpack file path
+ file_path: String,
+ /// Conflict policy: fail, overwrite, or skip
+ #[arg(long, value_parser = ["fail", "overwrite", "skip"])]
+ on_conflict: Option<String>,
},
// --- Interactive Tools ---
/// [Interactive] Interactive TUI file explorer
@@ -1058,12 +1068,18 @@ async fn main() {
} => handlers::handle_link(from_uri, to_uris, reason, ctx).await,
Commands::Unlink { from_uri, to_uri } => handlers::handle_unlink(from_uri, to_uri, ctx).await,
Commands::Export { uri, to } => handlers::handle_export(uri, to, ctx).await,
+ Commands::Backup { to } => handlers::handle_backup(to, ctx).await,
Commands::Import {
file_path,
target_uri,
- force,
- no_vectorize,
- } => handlers::handle_import(file_path, target_uri, force, no_vectorize, ctx).await,
+ on_conflict,
+ } => {
+ handlers::handle_import(file_path, target_uri, on_conflict, ctx).await
+ }
+ Commands::Restore {
+ file_path,
+ on_conflict,
+ } => handlers::handle_restore(file_path, on_conflict, ctx).await,
Commands::Wait { timeout } => {
let client = ctx.get_client();
commands::system::wait(&client, timeout, ctx.output_format, ctx.compact).await
@@ -1376,6 +1392,32 @@ mod tests {
assert!(result.is_err(), "removed write flags should not parse");
}
+ #[test]
+ fn cli_import_rejects_removed_vectorize_flag() {
+ let result = Cli::try_parse_from([
+ "ov",
+ "import",
+ "./exports/demo.ovpack",
+ "viking://resources/imported/",
+ "--no-vectorize",
+ ]);
+
+ assert!(result.is_err(), "removed import vectorize flag should not parse");
+ }
+
+ #[test]
+ fn cli_import_rejects_removed_force_flag() {
+ let result = Cli::try_parse_from([
+ "ov",
+ "import",
+ "./exports/demo.ovpack",
+ "viking://resources/imported/",
+ "--force",
+ ]);
+
+ assert!(result.is_err(), "removed import force flag should not parse");
+ }
+
#[test]
fn cli_parses_reindex_command() {
let result = Cli::try_parse_from([
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index cf46151d5..7a86389c0 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -363,6 +363,8 @@ Below are all HTTP API endpoints provided by OpenViking, grouped by functional m
|--------|------|-------------|------------|
| POST | `/api/v1/pack/export` | Export .ovpack | ROOT/ADMIN |
| POST | `/api/v1/pack/import` | Import .ovpack | ROOT/ADMIN |
+| POST | `/api/v1/pack/backup` | Back up public scopes | ROOT/ADMIN |
+| POST | `/api/v1/pack/restore` | Restore backup package | ROOT/ADMIN |
### File System
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 6011c14c0..5e106fc6c 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -986,8 +986,16 @@ Packages all resources under the specified URI into a `.ovpack` file for backup
**Processing Flow**:
1. Verify user permissions
2. Traverse resources under the specified URI
-3. Package into zip format (`.ovpack`)
-4. Return as file stream
+3. Write content files and the OVPack manifest
+4. Package into zip format (`.ovpack`)
+5. Return as file stream
+
+**Format Notes**:
+- The exported ZIP contains `<root>/_._ovpack_manifest.json`, the escaped ZIP name for `.ovpack_manifest.json`.
+- `entries[].path` is relative to the exported root; `""` means the root directory itself.
+- File entries include `size` and `sha256`; `content_sha256` covers the sorted file list of `path`, `size`, and `sha256`.
+- Raw embedding vectors and runtime fields such as `created_at`, `updated_at`, and `active_count` are not exported.
+- OVPack does not add package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
**Code Entry Points**:
- `openviking/server/routers/pack.py:export_ovpack` - HTTP router
@@ -1059,8 +1067,9 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data
**Processing Flow**:
1. Verify user permissions
2. Parse uploaded `.ovpack` file
-3. Import resources to target location
-4. Optionally trigger vectorization
+3. Validate manifest metadata, paths, file and directory sets, file sizes, and checksums
+4. Apply `on_conflict`
+5. Import resources to target location and rebuild vectors
**Code Entry Points**:
- `openviking/server/routers/pack.py:import_ovpack` - HTTP router
@@ -1075,11 +1084,23 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data
|-----------|------|----------|---------|-------------|
| temp_file_id | string | Yes | - | Temporary upload file ID (obtained via [temp_upload](02-resources.md#temp_upload)) |
| parent | string | Yes | - | Target parent URI (import to this location) |
-| force | bool | No | False | Whether to overwrite existing resources |
-| vectorize | bool | No | True | Whether to trigger vectorization |
+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
**Permission Requirements**: ROOT or ADMIN
+**Behavior Notes**:
+- Imports always rebuild vectors in the target environment. The API no longer accepts `vectorize` or `force`.
+- Session imports restore session files and do not trigger vectorization.
+- `on_conflict=fail` returns a structured `409 CONFLICT` when the target root already exists.
+- `on_conflict=overwrite` replaces the existing target root. `on_conflict=skip` keeps the existing target root and returns it without writing package contents. `skip` is root-level, not file-level.
+- Packages without a manifest are rejected by default because they cannot provide content integrity guarantees.
+- Packages with manifest entries are rejected if content files or directories are missing, extra files or directories are present, file sizes differ, per-file `sha256` differs, or `content_sha256` is missing or differs.
+- Packages whose manifest `format_version` is not the current supported version are rejected.
+- `.abstract.md` and `.overview.md` are restored as semantic sidecars. `.relations.json` and OVPack internals are excluded.
+- Manifest `context_type` must match the final import path semantics.
+- Top-level scope packages such as `viking://resources/` must be imported to `viking://`.
+- OVPack does not add import package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
+
#### 3. Usage Examples
**HTTP API**
@@ -1105,8 +1126,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"parent\": \"viking://resources/imported/\",
- \"force\": true,
- \"vectorize\": true
+ \"on_conflict\": \"overwrite\"
}"
```
@@ -1128,11 +1148,8 @@ client.initialize()
# Import .ovpack file
ov import ./exports/my-project.ovpack viking://resources/imported/
-# Force overwrite existing content
-ov import ./exports/my-project.ovpack viking://resources/imported/ --force
-
-# Skip vectorization
-ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize
+# Explicit conflict policy
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
```
**Response Example**
@@ -1149,6 +1166,83 @@ ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectoriz
}
```
+**Conflict Error Example**
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "CONFLICT",
+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
+ "details": {
+ "resource": "viking://resources/imported/my-project"
+ }
+ }
+}
+```
+
+---
+
+### backup_ovpack
+
+Back up public scope roots as a restore-only `.ovpack` file. The backup includes
+`resources`, `user`, `agent`, and `session`; it excludes internal runtime data
+such as `temp` and `queue`.
+
+```
+POST /api/v1/pack/backup
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/backup \
+ -H "X-API-Key: your-admin-key" \
+ --output openviking-backup.ovpack
+```
+
+CLI:
+
+```bash
+ov backup ./backups/openviking.ovpack
+```
+
+---
+
+### restore_ovpack
+
+Restore a backup package created by `backup_ovpack` to the original public scope
+roots. Regular import rejects backup packages. Non-session content is
+re-vectorized after restore; session files are restored without vectorization.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| temp_file_id | string | Yes | - | Temporary upload file ID |
+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
+
+```
+POST /api/v1/pack/restore
+Content-Type: application/json
+```
+
+```bash
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./backups/openviking.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+curl -X POST http://localhost:1933/api/v1/pack/restore \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\"}"
+```
+
+CLI:
+
+```bash
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
---
## Related Documentation
diff --git a/docs/en/concepts/01-architecture.md b/docs/en/concepts/01-architecture.md
index f7e2c0388..ad8ff884d 100644
--- a/docs/en/concepts/01-architecture.md
+++ b/docs/en/concepts/01-architecture.md
@@ -72,7 +72,7 @@ The Service layer decouples business logic from the transport layer, enabling re
| **SessionService** | Session management | session, sessions, commit, delete |
| **ResourceService** | Resource import | add_resource, add_skill, wait_processed |
| **RelationService** | Relation management | relations, link, unlink |
-| **PackService** | Import/export | export_ovpack, import_ovpack |
+| **PackService** | Import/export and backup/restore | export_ovpack, import_ovpack, backup_ovpack, restore_ovpack |
| **DebugService** | Debug service | observer (ObserverService) |
## Dual-Layer Storage
diff --git a/docs/en/guides/09-ovpack.md b/docs/en/guides/09-ovpack.md
index 46d97266f..e802e95da 100644
--- a/docs/en/guides/09-ovpack.md
+++ b/docs/en/guides/09-ovpack.md
@@ -39,11 +39,8 @@ Import an `.ovpack` file into OpenViking.
# Basic import
openviking import ./exports/my-project.ovpack viking://resources/imported/
-# Force overwrite
-openviking import ./exports/my-project.ovpack viking://resources/imported/ --force
-
-# Skip vectorization (faster)
-openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize
+# Explicit conflict policy
+openviking import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
```
**Python SDK**
@@ -57,8 +54,7 @@ async def import_example():
imported_uri = await client.import_ovpack(
file_path="./exports/my-project.ovpack",
parent="viking://resources/imported/",
- force=True,
- vectorize=True
+ on_conflict="overwrite"
)
print(f"Import successful: {imported_uri}")
await client.wait_processed()
@@ -86,11 +82,83 @@ curl -X POST http://localhost:1933/api/v1/pack/import \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"parent\": \"viking://resources/imported/\",
- \"force\": true,
- \"vectorize\": true
+ \"on_conflict\": \"overwrite\"
}"
```
+## Format Notes
+
+OVPack v2 files are standard ZIP archives. Each package contains an OpenViking
+manifest at `<root>/_._ovpack_manifest.json`; this is the ZIP-escaped form of the
+hidden filename `.ovpack_manifest.json`.
+
+The manifest records `kind`, `format_version`, the exported root, content
+entries, and portable vector scalar metadata. In `entries`, `path` is relative to
+the exported root. An empty path (`""`) means the root directory itself, for
+example `my-project/`.
+
+Example manifest for a package exported from `viking://resources/demo/`:
+
+```json
+{
+ "kind": "openviking.ovpack",
+ "format_version": 2,
+ "root": {
+ "name": "demo",
+ "uri": "viking://resources/demo",
+ "scope": "resources"
+ },
+ "entries": [
+ {
+ "path": "",
+ "kind": "directory"
+ },
+ {
+ "path": "notes.txt",
+ "kind": "file",
+ "size": 5,
+ "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+ }
+ ],
+ "content_sha256": "b2a6e9582119c7510d68e3446de3e71a486934bf450d68f65596259ed1cf7997",
+ "vectors": {}
+}
+```
+
+For packages with manifest entries, import validates the ZIP file and directory
+set, per-file `size`, per-file `sha256`, and top-level `content_sha256` before
+writing any resources. Missing, extra, or modified content entries, and missing
+or mismatched v2 `content_sha256`, are rejected. This is an integrity check for the package
+contents, not a signature or authentication mechanism if both the manifest and
+content can be rewritten.
+
+Raw embedding vectors are not exported. Runtime fields such as `created_at`,
+`updated_at`, and `active_count` are also not exported; imports rebuild vectors
+and runtime state in the target environment. Session packages restore session
+files and do not trigger vectorization. Packages without a manifest are rejected
+by default because OpenViking cannot verify their file set or content checksums.
+Packages with a manifest validate `kind` and `format_version`, and packages
+whose format version is not the current supported version are rejected.
+`.abstract.md` and `.overview.md` are restored as semantic sidecar files;
+`.relations.json` and OVPack internals are excluded.
+
+Manifest scalar `context_type`, when present, is treated as exported scalar
+metadata only. Import compatibility is based on the source and target URI scopes;
+the final `context_type` is derived again from the target URI during
+vectorization.
+
+Top-level scope packages such as `viking://resources/`, `viking://user/`,
+`viking://agent/`, and `viking://session/` must be imported to `viking://`.
+Regular import also requires the manifest root scope to match the final target
+root scope. Structured scopes (`user`, `agent`, and `session`) cannot be imported
+in a way that changes the root depth, such as importing a session package into a
+concrete session URI and creating `session/sess_123/sess_123`.
+Full backups use the separate `backup` / `restore` interface, not regular
+import parent semantics.
+OVPack itself does not add package-size, file-count, or directory-depth limits;
+the practical limit comes from ZIP, the storage backend, and the runtime
+environment.
+
## Memory Import and Export
OpenViking memories are stored under fixed directory structures:
@@ -107,7 +175,7 @@ When migrating memories with OVPack, you must import the `.ovpack` into the pare
openviking export viking://user/default/memories/ ./exports/user-memories.ovpack
# Import into the user space root (imports to viking://user/default/memories/)
-openviking import ./exports/user-memories.ovpack viking://user/default/ --force
+openviking import ./exports/user-memories.ovpack viking://user/default/ --on-conflict overwrite
```
### Export/Import Agent Memories (CLI)
@@ -115,11 +183,11 @@ openviking import ./exports/user-memories.ovpack viking://user/default/ --force
```bash
# isolate_agent_scope_by_user = false
openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack
-openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force
+openviking import ./exports/agent-memories.ovpack viking://agent/default/ --on-conflict overwrite
# isolate_agent_scope_by_user = true
openviking export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack
-openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --force
+openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --on-conflict overwrite
```
### Export/Import Memories (Python SDK)
@@ -139,8 +207,7 @@ async def export_import_user_memories():
await client.import_ovpack(
file_path="./exports/user-memories.ovpack",
parent="viking://user/default/",
- force=True,
- vectorize=True,
+ on_conflict="overwrite",
)
finally:
await client.close()
@@ -156,8 +223,7 @@ async def export_import_agent_memories():
await client.import_ovpack(
file_path="./exports/agent-memories.ovpack",
parent="viking://agent/default/",
- force=True,
- vectorize=True,
+ on_conflict="overwrite",
)
finally:
await client.close()
@@ -188,22 +254,51 @@ curl -X POST http://localhost:1933/api/v1/pack/import \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"parent\": \"viking://user/default/\",
- \"force\": true,
- \"vectorize\": true
+ \"on_conflict\": \"overwrite\"
}"
```
### Vectorization on Import
-- Vectorization is enabled by default (useful for `find/search`).
-- For faster restore, you can disable it and process later with `--no-vectorize`:
+Imports always rebuild vectors in the target environment for `find/search`.
+OVPack no longer exposes an import option to disable vectorization. Session
+imports are restored as files only and are not vectorized.
+
+### Session Import and Export
```bash
-openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize
+openviking export viking://session/sess_123/ ./exports/sess_123.ovpack
+openviking import ./exports/sess_123.ovpack viking://session/ --on-conflict overwrite
```
+The restored root is `viking://session/sess_123/`.
+
+### Scope Root Import
+
+```bash
+openviking export viking://resources/ ./backups/resources.ovpack
+openviking import ./backups/resources.ovpack viking:// --on-conflict overwrite
+```
+
+Scope-root packages cannot be imported under another scope directory.
+
## Use Cases
+### Full Backup and Migration
+
+Use a backup package for full migration instead of regular `export/import`
+parent-directory semantics:
+
+```bash
+openviking backup ./backups/openviking.ovpack
+openviking restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
+Backup packages restore to the original public scope roots: `resources`, `user`,
+`agent`, and `session`. They exclude internal/runtime data such as `temp`,
+`queue`, lock files, OVPack manifests, and `.relations.json`. Non-session
+content is re-vectorized; session files are only restored.
+
### Resource Backup
```bash
DATE=$(date +%Y%m%d)
@@ -216,7 +311,7 @@ openviking export viking://resources/ ./backups/backup_${DATE}.ovpack
openviking export viking://resources/my-project/ ./migration.ovpack
# Import on Machine B
-openviking import ./migration.ovpack viking://resources/ --force
+openviking import ./migration.ovpack viking://resources/ --on-conflict overwrite
```
### Resource Sharing
@@ -234,7 +329,7 @@ openviking import ./shared-docs.ovpack viking://resources/team-shared/
A: Yes! OVPack is a standard ZIP format and can be opened with any compression tool.
**Q: What if large OVPack imports are slow?**
-A: Use `--no-vectorize` for fast import, then vectorize later.
+A: Imports now always rebuild vectors. If import time is too high, split the content into smaller OVPack files and import them in batches.
**Q: How to handle duplicate resources during import?**
-A: Use `--force` to overwrite existing resources.
+A: Use `--on-conflict overwrite` to replace existing resources, or `--on-conflict skip` to keep them.
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 554244cb9..a59a1b942 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -363,6 +363,8 @@ JSON 输出 - 错误:
|------|------|------|------|
| POST | `/api/v1/pack/export` | 导出 .ovpack 文件 | ROOT/ADMIN |
| POST | `/api/v1/pack/import` | 导入 .ovpack 文件 | ROOT/ADMIN |
+| POST | `/api/v1/pack/backup` | 备份公开 scope | ROOT/ADMIN |
+| POST | `/api/v1/pack/restore` | 恢复备份包 | ROOT/ADMIN |
### 文件系统端点
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index 6dd230d34..2922095da 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -986,8 +986,16 @@ openviking unlink viking://resources/docs/auth/ viking://resources/docs/security
**处理流程**:
1. 验证用户权限
2. 遍历指定 URI 下的资源
-3. 打包成 zip 格式(.ovpack)
-4. 以文件流形式返回
+3. 写入内容文件和 OVPack manifest
+4. 打包成 zip 格式(.ovpack)
+5. 以文件流形式返回
+
+**格式说明**:
+- 导出的 ZIP 会包含 `<root>/_._ovpack_manifest.json`,这是 `.ovpack_manifest.json` 在 ZIP 内的转义名称。
+- `entries[].path` 是相对导出 root 的路径;`""` 表示 root 目录本身。
+- 文件条目包含 `size` 和 `sha256`;`content_sha256` 覆盖按路径排序后的文件列表(`path`、`size`、`sha256`)。
+- 原始 embedding 向量以及 `created_at`、`updated_at`、`active_count` 等运行态字段不会被导出。
+- OVPack 不额外设置包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
**代码入口**:
- `openviking/server/routers/pack.py:export_ovpack` - HTTP 路由
@@ -1059,8 +1067,9 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack
**处理流程**:
1. 验证用户权限
2. 解析上传的 `.ovpack` 文件
-3. 导入资源到目标位置
-4. 可选地触发向量化
+3. 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum
+4. 应用 `on_conflict`
+5. 导入资源到目标位置,并重建向量
**代码入口**:
- `openviking/server/routers/pack.py:import_ovpack` - HTTP 路由
@@ -1075,11 +1084,23 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack
|------|------|------|--------|------|
| temp_file_id | string | 是 | - | 临时上传文件 ID(通过 [temp_upload](02-resources.md#temp_upload) 获取) |
| parent | string | 是 | - | 目标父级 URI(导入到此处) |
-| force | bool | 否 | False | 是否覆盖已有资源 |
-| vectorize | bool | 否 | True | 是否触发向量化 |
+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
**权限要求**:ROOT 或 ADMIN
+**行为说明**:
+- 导入后总是在目标环境重建向量。API 已不再接受 `vectorize` 或 `force`。
+- Session 导入只恢复 session 文件状态,不触发向量化。
+- `on_conflict=fail` 且目标 root 已存在时,会返回结构化的 `409 CONFLICT`。
+- `on_conflict=overwrite` 会替换已有目标 root。`on_conflict=skip` 会保留已有目标 root,并直接返回该路径,不写入包内容。`skip` 是 root 级跳过,不是文件级补齐。
+- 默认拒绝没有 manifest 的包,因为这类包无法提供内容完整性校验。
+- 带 manifest entries 的包如果缺少内容文件或目录、混入额外文件或目录、文件大小不同、单文件 `sha256` 不同,或整体 `content_sha256` 缺失/不匹配,都会被拒绝导入。
+- manifest `format_version` 不是当前支持版本的包会被拒绝。
+- `.abstract.md` 和 `.overview.md` 会作为语义侧边文件恢复;`.relations.json` 和 OVPack 内部文件会被排除。
+- manifest `context_type` 必须和最终导入路径语义一致。
+- `viking://resources/` 这类顶级 scope 包必须导入到 `viking://`。
+- OVPack 不额外设置导入包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
+
#### 3. 使用示例
**HTTP API**
@@ -1105,8 +1126,7 @@ curl -X POST http://localhost:1933/api/v1/pack/import \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"parent\": \"viking://resources/imported/\",
- \"force\": true,
- \"vectorize\": true
+ \"on_conflict\": \"overwrite\"
}"
```
@@ -1128,11 +1148,8 @@ client.initialize()
# 导入 .ovpack 文件
ov import ./exports/my-project.ovpack viking://resources/imported/
-# 强制覆盖已有内容
-ov import ./exports/my-project.ovpack viking://resources/imported/ --force
-
-# 不进行向量化
-ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize
+# 显式冲突策略
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
```
**响应示例**
@@ -1149,6 +1166,81 @@ ov import ./exports/my-project.ovpack viking://resources/imported/ --no-vectoriz
}
```
+**冲突错误示例**
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "CONFLICT",
+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
+ "details": {
+ "resource": "viking://resources/imported/my-project"
+ }
+ }
+}
+```
+
+---
+
+### backup_ovpack
+
+将公开 scope root 备份为只能通过 restore 恢复的 `.ovpack` 文件。备份包含
+`resources`、`user`、`agent`、`session`,不包含 `temp`、`queue` 等内部运行态数据。
+
+```
+POST /api/v1/pack/backup
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/backup \
+ -H "X-API-Key: your-admin-key" \
+ --output openviking-backup.ovpack
+```
+
+CLI:
+
+```bash
+ov backup ./backups/openviking.ovpack
+```
+
+---
+
+### restore_ovpack
+
+恢复 `backup_ovpack` 生成的备份包到原始公开 scope root。普通 import 不接受备份包。
+非 session 内容恢复后重新向量化;session 只恢复文件状态。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| temp_file_id | string | 是 | - | 临时上传文件 ID |
+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
+
+```
+POST /api/v1/pack/restore
+Content-Type: application/json
+```
+
+```bash
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./backups/openviking.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+curl -X POST http://localhost:1933/api/v1/pack/restore \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\"}"
+```
+
+CLI:
+
+```bash
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
---
## 相关文档
diff --git a/docs/zh/concepts/01-architecture.md b/docs/zh/concepts/01-architecture.md
index a2e95ac39..ea569c8d5 100644
--- a/docs/zh/concepts/01-architecture.md
+++ b/docs/zh/concepts/01-architecture.md
@@ -71,7 +71,7 @@ Service 层将业务逻辑与传输层解耦,便于 HTTP Server 和 CLI 复用
| **SessionService** | 会话管理 | session, sessions, commit, delete |
| **ResourceService** | 资源导入 | add_resource, add_skill, wait_processed |
| **RelationService** | 关联管理 | relations, link, unlink |
-| **PackService** | 导入导出 | export_ovpack, import_ovpack |
+| **PackService** | 导入导出、备份恢复 | export_ovpack, import_ovpack, backup_ovpack, restore_ovpack |
| **DebugService** | 调试服务 | observer (ObserverService) |
## 双层存储
diff --git a/docs/zh/guides/09-ovpack.md b/docs/zh/guides/09-ovpack.md
index a6e798fc6..f516e9311 100644
--- a/docs/zh/guides/09-ovpack.md
+++ b/docs/zh/guides/09-ovpack.md
@@ -1,251 +1,394 @@
# OVPack 导入导出
-OVPack 是 OpenViking 的打包格式,用于导出/导入任意上下文子树(例如资源、记忆),以便备份、迁移和分享。
+OVPack 是 OpenViking 的上下文打包格式,用来把一个 `viking://` 子树导出成
+`.ovpack` 文件,再导入到另一个 OpenViking 环境。它适合备份、迁移、分享资源或记忆
+目录;它不是长期归档格式,也不是带签名的安全发布格式。
-## 快速开始
+## 适用边界
-### 导出资源
+OVPack 可以处理这些公开作用域:
-将 OpenViking 中的资源导出为 `.ovpack` 文件。
+- `viking://resources/...`
+- `viking://user/...`
+- `viking://agent/...`
+- `viking://session/...`
-**CLI**
-```bash
-openviking export viking://resources/my-project/ ./exports/my-project.ovpack
-```
+OVPack 支持导出公开 scope root,例如 `viking://resources/`、`viking://user/`、
+`viking://agent/`、`viking://session/`;这类顶级 scope 包只能导入到 `viking://`。
+全量备份使用单独的 `backup` / `restore` 接口,自动包含这些公开 scope root。
+`temp`、`queue` 等内部作用域不属于 OVPack 迁移范围。
-**Python SDK**
-```python
-from openviking import AsyncOpenViking
+`.abstract.md` 和 `.overview.md` 会作为语义侧边文件随包恢复;`.relations.json`、锁文件、
+manifest 等内部文件不会进入包。导入后 OpenViking 会在目标环境重新生成语义和向量;session
+包只恢复 session 文件状态,不触发向量化。导入接口不再提供 `vectorize` 或 `force` 参数;
+冲突处理统一使用 `on_conflict`。OVPack 本身不再设置额外的包大小、文件数量或目录深度上限;
+实际可处理规模由 ZIP、存储后端和运行环境决定。
-async def export_example():
- client = AsyncOpenViking()
- await client.initialize()
- try:
- exported_path = await client.export_ovpack(
- uri="viking://resources/my-project/",
- to="./exports/my-project.ovpack"
- )
- print(f"导出成功: {exported_path}")
- finally:
- await client.close()
-```
+## 快速开始
+
+### CLI
-**HTTP API**
```bash
-curl -X POST http://localhost:1933/api/v1/pack/export \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://resources/my-project/",
- "to": "./exports/my-project.ovpack"
- }'
-```
+# 导出资源目录
+ov export viking://resources/my-project/ ./exports/my-project.ovpack
+
+# 导入到目标父目录
+ov import ./exports/my-project.ovpack viking://resources/imported/
-### 导入资源
+# 目标 root 已存在时覆盖
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
+```
-将 `.ovpack` 文件导入到 OpenViking 中。
+导入的第二个参数是“父目录”,不是最终 root。假设包内 root 名是 `my-project`:
-**CLI**
-```bash
-# 基本导入
-openviking import ./exports/my-project.ovpack viking://resources/imported/
+```text
+ov import ./exports/my-project.ovpack viking://resources/imported/
+```
-# 强制覆盖
-openviking import ./exports/my-project.ovpack viking://resources/imported/ --force
+导入结果是:
-# 跳过向量化(更快)
-openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize
+```text
+viking://resources/imported/my-project
```
-**Python SDK**
+### Python SDK
+
```python
from openviking import AsyncOpenViking
-async def import_example():
+
+async def export_and_import():
client = AsyncOpenViking()
await client.initialize()
try:
+ await client.export_ovpack(
+ uri="viking://resources/my-project/",
+ to="./exports/my-project.ovpack",
+ )
+
imported_uri = await client.import_ovpack(
file_path="./exports/my-project.ovpack",
parent="viking://resources/imported/",
- force=True,
- vectorize=True
+ on_conflict="overwrite",
)
- print(f"导入成功: {imported_uri}")
+ print(imported_uri)
+
+ # 导入会触发目标环境重新向量化;需要检索前可等待后台任务完成。
await client.wait_processed()
finally:
await client.close()
```
-**HTTP API**
+### HTTP API
+
+HTTP 导出接口直接返回文件流;HTTP 导入必须先上传本地 `.ovpack` 文件,再用
+`temp_file_id` 导入。
+
+```bash
+# 导出
+curl -X POST http://localhost:1933/api/v1/pack/export \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{"uri": "viking://resources/my-project/"}' \
+ --output my-project.ovpack
+```
+
```bash
# 第一步:上传本地 ovpack 文件
-# 默认使用本地临时存储。
-# 只有在明确需要分布式共享临时上传时,才额外传:-F "upload_mode=shared"
-# Python HTTP client / CLI 也可以改为在 ovcli.conf 中设置:upload.mode = "shared"
TEMP_FILE_ID=$(
curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-key" \
- -F 'file=@./exports/my-project.ovpack' \
- | jq -r '.result.temp_file_id'
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./exports/my-project.ovpack" \
+ | jq -r ".result.temp_file_id"
)
-# 第二步:使用 temp_file_id 导入
+# 第二步:导入
curl -X POST http://localhost:1933/api/v1/pack/import \
-H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
+ -H "X-API-Key: your-admin-key" \
-d "{
\"temp_file_id\": \"$TEMP_FILE_ID\",
\"parent\": \"viking://resources/imported/\",
- \"force\": true,
- \"vectorize\": true
+ \"on_conflict\": \"overwrite\"
}"
```
-## 记忆导入导出
+HTTP 接口不接受本机路径字段,例如 `file_path`、`temp_path`。本地文件读取和上传由 CLI 或
+SDK 客户端完成,服务端只消费 `temp_file_id`。
+
+## 冲突策略
+
+`on_conflict` 只在导入 root 已存在时生效。
+
+| 值 | 行为 |
+| --- | --- |
+| `fail` | 默认值。目标 root 已存在时返回 `409 CONFLICT`。 |
+| `overwrite` | 删除已有 root,再写入包内容。 |
+| `skip` | 保留已有 root,直接返回该 URI,不写入包内容。 |
+
+`skip` 是 root 级跳过,不是文件级补齐导入:只要目标 root 已存在,就不会写入包内缺失文件。
+
+示例错误:
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "CONFLICT",
+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
+ "details": {
+ "resource": "viking://resources/imported/my-project"
+ }
+ }
+}
+```
+
+## 包结构
+
+OVPack v2 是标准 ZIP 文件。ZIP 内部以一个 root 目录包住所有内容,并包含一个 manifest:
+
+```text
+my-project/
+my-project/notes.txt
+my-project/_._overview.md
+my-project/_._ovpack_manifest.json
+```
+
+`_._ovpack_manifest.json` 是 `.ovpack_manifest.json` 在 ZIP 内的转义名称。OpenViking 会把
+普通内容里的点文件名也按同一规则转义,例如 `.overview.md` 在 ZIP 内是 `_._overview.md`。
+
+一个最小 manifest 示例:
+
+```json
+{
+ "kind": "openviking.ovpack",
+ "format_version": 2,
+ "root": {
+ "name": "my-project",
+ "uri": "viking://resources/my-project",
+ "scope": "resources"
+ },
+ "entries": [
+ {
+ "path": "",
+ "kind": "directory"
+ },
+ {
+ "path": "notes.txt",
+ "kind": "file",
+ "size": 5,
+ "sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+ }
+ ],
+ "content_sha256": "b2a6e9582119c7510d68e3446de3e71a486934bf450d68f65596259ed1cf7997",
+ "vectors": {
+ "": [
+ {
+ "level": 0,
+ "text": "Project summary",
+ "scalars": {
+ "context_type": "resource",
+ "level": 0,
+ "abstract": "Project summary"
+ }
+ }
+ ]
+ }
+}
+```
+
+字段说明:
+
+- `kind` 固定为 `openviking.ovpack`。
+- `format_version` 当前为 `2`。低于或高于当前支持版本的包都会被拒绝。
+- `root.name` 是导入时创建的 root 名称。
+- `entries[].path` 是相对 root 的路径。`""` 表示 root 目录本身。
+- 文件条目包含 `size` 和 `sha256`。
+- `content_sha256` 覆盖按路径排序后的文件列表,元素只包含 `path`、`size`、`sha256`。
+- `vectors` 只保存可迁移的标量和目录摘要文本,不保存原始 embedding 向量。
+- 包内如果带有 `context_type`,只作为导出时的标量信息;导入校验不依赖它,最终
+ `context_type` 以目标路径推导结果为准。
+
+当前会导出的向量标量字段是:
+
+```text
+type, context_type, level, name, description, tags, abstract
+```
+
+这些运行态字段不会导出,会在目标环境重新生成:
+
+```text
+created_at, updated_at, active_count
+```
+
+## 导入校验
-OpenViking 的记忆会写入固定的目录结构中:
+导入会先校验包,再写入目标目录。核心规则如下:
-- 用户记忆:`viking://user/{user_space}/memories/`
-- Agent 记忆:`viking://agent/{agent_id}/memories/` 或 `viking://agent/{agent_id}/user/{user_id}/memories/`
+1. ZIP 路径必须在同一个 root 下,不能包含绝对路径、反斜杠、盘符或 `..`。
+2. 必须存在 `<root>/_._ovpack_manifest.json`。
+3. manifest 必须是合法 JSON,`kind` 和 `format_version` 必须可识别。
+4. `entries` 中声明的文件和目录集合必须和 ZIP 内容一致。
+5. 每个文件的 `size` 和 `sha256` 必须匹配实际内容。
+6. v2 包必须带 `content_sha256`,并且整体 checksum 必须匹配。
+7. manifest root 的 source scope 必须和最终导入 root 的 target scope 一致。
+8. `user`、`agent`、`session` 这类结构化 scope 不能通过导入改变 root 层级。
+9. `.relations.json`、manifest、锁文件等内部文件不会作为普通内容导入。
-使用 OVPack 迁移记忆时,必须把 `.ovpack` 导入到对应 space 的父目录(而不是随便一个目录),否则会变成例如 `.../memories/memories/...` 的路径,OpenViking 将无法按“记忆”语义访问和使用这些文件。
+如果旧包没有 manifest,会被拒绝:
-### 导出/导入用户记忆(CLI)
+```text
+INVALID_ARGUMENT: Missing ovpack manifest
+```
+
+如果内容被改动,例如 manifest 里声明 `notes.txt` 的 sha256 是 `hello`,但 ZIP 里实际内容
+变成 `jello`,会被拒绝:
+
+```text
+INVALID_ARGUMENT: ovpack file sha256 does not match manifest
+```
+
+这个校验保证的是“包内容没有偏离 manifest”。如果攻击者能同时改 manifest 和文件内容,
+它不能替代签名、可信发布链或访问控制。
+
+如果包从 `viking://session/sess_123` 导出,却导入到 `viking://resources/`,会因为
+source scope 和 target scope 不一致被拒绝。导入到 `viking://session/sess_123/` 也会
+被拒绝,因为它会生成 `viking://session/sess_123/sess_123` 这种嵌套 root。
+
+## 旧包和未来版本
+
+默认导入只接受带 manifest 的 OVPack。旧版无 manifest 包没有文件集合和 checksum 信息,
+无法判断是否混入或删改内容,因此默认拒绝。需要迁移旧包时,应先在可信环境中用旧版本导入,
+再用当前版本重新导出。
+
+开发期间生成过的 v2 预览包如果缺少 `content_sha256`,也会被拒绝。处理方式同样是重新导出。
+
+如果 manifest 的 `format_version` 不是当前支持版本,会返回不支持的版本错误。低版本不会自动
+兼容;处理方式是在可信环境中重新导出为当前支持格式。未来版本包则应升级 OpenViking,或由
+支持该版本的环境重新导出成当前支持的格式。
+
+## 记忆迁移
+
+记忆目录有固定结构。导入时要把包导入到“对应目录的父目录”,避免产生重复路径。
+
+### 用户记忆
```bash
-# 导出:整个用户 memories 子树
-openviking export viking://user/default/memories/ ./exports/user-memories.ovpack
+# 导出整个用户 memories 子树
+ov export viking://user/default/memories/ ./exports/user-memories.ovpack
+
+# 导入到 user space 根目录,结果是 viking://user/default/memories/
+ov import ./exports/user-memories.ovpack viking://user/default/ --on-conflict overwrite
+```
-# 导入:注意 parent 需要是 user space 根目录(导入后会生成 viking://user/default/memories/)
-openviking import ./exports/user-memories.ovpack viking://user/default/ --force
+不要导入到 `viking://user/default/memories/`,否则会得到:
+
+```text
+viking://user/default/memories/memories
```
-### 导出/导入 Agent 记忆(CLI)
+### Agent 记忆
```bash
# isolate_agent_scope_by_user = false
-openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack
-openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force
+ov export viking://agent/default/memories/ ./exports/agent-memories.ovpack
+ov import ./exports/agent-memories.ovpack viking://agent/default/ --on-conflict overwrite
# isolate_agent_scope_by_user = true
-openviking export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack
-openviking import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --force
+ov export viking://agent/default/user/alice/memories/ ./exports/agent-memories.ovpack
+ov import ./exports/agent-memories.ovpack viking://agent/default/user/alice/ --on-conflict overwrite
```
-### 导出/导入记忆(Python SDK)
+## Session 迁移
-```python
-from openviking import AsyncOpenViking
+Session 包按备份恢复语义处理:恢复原 session id,不进行向量化。
-async def export_import_user_memories():
- client = AsyncOpenViking()
- await client.initialize()
- try:
- await client.export_ovpack(
- uri="viking://user/default/memories/",
- to="./exports/user-memories.ovpack",
- )
+```bash
+ov export viking://session/sess_123/ ./exports/sess_123.ovpack
+ov import ./exports/sess_123.ovpack viking://session/ --on-conflict overwrite
+```
- await client.import_ovpack(
- file_path="./exports/user-memories.ovpack",
- parent="viking://user/default/",
- force=True,
- vectorize=True,
- )
- finally:
- await client.close()
+导入结果是:
-async def export_import_agent_memories():
- client = AsyncOpenViking()
- await client.initialize()
- try:
- await client.export_ovpack(
- uri="viking://agent/default/memories/",
- to="./exports/agent-memories.ovpack",
- )
- await client.import_ovpack(
- file_path="./exports/agent-memories.ovpack",
- parent="viking://agent/default/",
- force=True,
- vectorize=True,
- )
- finally:
- await client.close()
+```text
+viking://session/sess_123/
```
-### 导出/导入记忆(HTTP API)
+如果导出整个 session scope:
```bash
-# 导出用户记忆
-curl -X POST http://localhost:1933/api/v1/pack/export \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://user/default/memories/",
- "to": "./exports/user-memories.ovpack"
- }'
-
-# 导入用户记忆(先上传,再用 temp_file_id 导入)
-TEMP_FILE_ID=$(
- curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-key" \
- -F 'file=@./exports/user-memories.ovpack' \
- | jq -r '.result.temp_file_id'
-)
-curl -X POST http://localhost:1933/api/v1/pack/import \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d "{
- \"temp_file_id\": \"$TEMP_FILE_ID\",
- \"parent\": \"viking://user/default/\",
- \"force\": true,
- \"vectorize\": true
- }"
+ov export viking://session/ ./exports/session.ovpack
+ov import ./exports/session.ovpack viking:// --on-conflict overwrite
```
-### 导入后是否向量化
+## 常见场景
-- 默认会向量化(便于 `find/search` 检索)。
-- 如果只做快速恢复、稍后再统一处理,可使用 `--no-vectorize`:
+### 全量备份和迁移
+
+全量迁移使用专门的备份包,而不是普通 `export/import` 的父目录语义:
```bash
-openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize
+ov backup ./backups/openviking.ovpack
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
```
-## 使用场景
+备份包恢复到原始公开 scope root:`resources`、`user`、`agent`、`session`。
+它不包含 `temp`、`queue`、锁文件、manifest、`.relations.json` 等内部或运行态数据。
+非 session 内容恢复后重新向量化;session 只恢复文件状态。
+
+### 备份资源
-### 资源备份
```bash
DATE=$(date +%Y%m%d)
-openviking export viking://resources/ ./backups/backup_${DATE}.ovpack
+ov export viking://resources/ ./backups/resources_${DATE}.ovpack
+
+# 恢复整个 resources scope 时,父目录必须是 viking://
+ov import ./backups/resources_${DATE}.ovpack viking:// --on-conflict overwrite
```
-### 资源迁移
+### 跨环境迁移
+
```bash
-# 机器 A 导出
-openviking export viking://resources/my-project/ ./migration.ovpack
+# 机器 A
+ov export viking://resources/my-project/ ./migration.ovpack
-# 机器 B 导入
-openviking import ./migration.ovpack viking://resources/ --force
+# 机器 B
+ov import ./migration.ovpack viking://resources/ --on-conflict overwrite
```
-### 资源分享
-```bash
-# 导出
-openviking export viking://resources/shared-docs/ ./shared-docs.ovpack
+### 分享一组资源
-# 接收者导入
-openviking import ./shared-docs.ovpack viking://resources/team-shared/
+```bash
+ov export viking://resources/shared-docs/ ./shared-docs.ovpack
+ov import ./shared-docs.ovpack viking://resources/team-shared/
```
+## 常见错误
+
+| 错误 | 常见原因 | 处理方式 |
+| --- | --- | --- |
+| `Missing ovpack manifest` | 旧版无 manifest 包 | 在可信环境重新导出。 |
+| `Missing ovpack manifest content_sha256` | 开发期 v2 预览包缺少整体 checksum | 重新导出。 |
+| `sha256 does not match manifest` | 文件内容和 manifest 不一致 | 丢弃该包,或从可信源重新导出。 |
+| `ovpack entries do not match manifest` | ZIP 中缺文件/目录,或混入额外文件/目录 | 丢弃该包,或重新导出。 |
+| `source scope does not match target scope` | 将包导入到了不同 scope,例如 session 导入 resources | 导入到同 scope 的父目录。 |
+| `source path is incompatible with target path` | 结构化 scope 的导入会改变 root 层级,例如 session 导入具体 session 内部 | 导入到正确的系统父目录。 |
+| `Top-level scope ovpack packages must be imported to viking://` | 将 `resources`/`user`/`agent`/`session` 顶级包导入了非根父目录 | 改为导入 `viking://`。 |
+| `Unsupported ovpack format_version` | 包格式版本不是当前支持版本 | 升级 OpenViking 或重新导出为当前支持版本。 |
+| `Resource already exists` | 目标 root 已存在 | 使用 `--on-conflict overwrite` 或 `--on-conflict skip`。 |
+
## 常见问题
-**Q: OVPack 文件可以手动解压查看吗?**
-A: 可以!OVPack 是标准的 ZIP 格式,可以用任何解压工具打开。
+**OVPack 可以手动解压查看吗?**
+
+可以。OVPack 是 ZIP 文件,可以用普通解压工具查看。不要手动改包后再导入;修改内容会破坏
+manifest 校验。
+
+**大包导入很慢怎么办?**
+
+导入会重建目标环境的语义和向量。大包迁移建议按目录拆成多个 OVPack 分批导入。
-**Q: 大体积 OVPack 导入很慢怎么办?**
-A: 使用 `--no-vectorize` 先快速导入,之后再统一向量化。
+**为什么不兼容旧版无 manifest 包?**
-**Q: 导入时如何处理重名资源?**
-A: 使用 `--force` 参数覆盖已存在的资源。
+旧包没有可验证的文件列表,也没有 checksum。默认兼容会让被删改或混入文件的包直接写入目标
+环境,风险高于收益。
diff --git a/openviking/async_client.py b/openviking/async_client.py
index b68514577..61dd4436e 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -563,8 +563,24 @@ class AsyncOpenViking:
await self._ensure_initialized()
return await self._client.export_ovpack(uri, to)
+ async def backup_ovpack(self, to: str) -> str:
+ """
+ Back up public OpenViking scopes as a restore-only .ovpack file.
+
+ Args:
+ to: Target file path
+
+ Returns:
+ Exported backup file path
+ """
+ await self._ensure_initialized()
+ return await self._client.backup_ovpack(to)
+
async def import_ovpack(
- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True
+ self,
+ file_path: str,
+ parent: str,
+ on_conflict: Optional[str] = None,
) -> str:
"""
Import local .ovpack file to specified parent path.
@@ -572,14 +588,38 @@ class AsyncOpenViking:
Args:
file_path: Local .ovpack file path
parent: Target parent URI (e.g., viking://user/alice/resources/references/)
- force: Whether to force overwrite existing resources (default: False)
- vectorize: Whether to trigger vectorization (default: True)
+ on_conflict: One of "fail", "overwrite", or "skip"
Returns:
Imported root resource URI
"""
await self._ensure_initialized()
- return await self._client.import_ovpack(file_path, parent, force=force, vectorize=vectorize)
+ return await self._client.import_ovpack(
+ file_path,
+ parent,
+ on_conflict=on_conflict,
+ )
+
+ async def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """
+ Restore a backup .ovpack file to its original public scope roots.
+
+ Args:
+ file_path: Local backup .ovpack file path
+ on_conflict: One of "fail", "overwrite", or "skip"
+
+ Returns:
+ Restored root URI
+ """
+ await self._ensure_initialized()
+ return await self._client.restore_ovpack(
+ file_path,
+ on_conflict=on_conflict,
+ )
# ============= Debug methods =============
diff --git a/openviking/client/local.py b/openviking/client/local.py
index b080bb26a..9f1e1eac9 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -553,16 +553,34 @@ class LocalClient(BaseClient):
"""Export context as .ovpack file."""
return await self._service.pack.export_ovpack(uri, to, ctx=self._ctx)
+ async def backup_ovpack(self, to: str) -> str:
+ """Back up public scopes as a restore-only .ovpack file."""
+ return await self._service.pack.backup_ovpack(to, ctx=self._ctx)
+
async def import_ovpack(
self,
file_path: str,
parent: str,
- force: bool = False,
- vectorize: bool = True,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import .ovpack file."""
return await self._service.pack.import_ovpack(
- file_path, parent, ctx=self._ctx, force=force, vectorize=vectorize
+ file_path,
+ parent,
+ ctx=self._ctx,
+ on_conflict=on_conflict,
+ )
+
+ async def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore backup .ovpack file."""
+ return await self._service.pack.restore_ovpack(
+ file_path,
+ ctx=self._ctx,
+ on_conflict=on_conflict,
)
# ============= Debug =============
diff --git a/openviking/server/error_mapping.py b/openviking/server/error_mapping.py
index 505033b42..e9b8079b0 100644
--- a/openviking/server/error_mapping.py
+++ b/openviking/server/error_mapping.py
@@ -391,6 +391,10 @@ def is_invalid_uri_error(exc: Exception) -> bool:
)
+def _not_found_error(resource: str | None, resource_type: str) -> NotFoundError:
+ return NotFoundError(resource or "", resource_type)
+
+
def map_exception(
exc: Exception,
*,
@@ -404,7 +408,7 @@ def map_exception(
if isinstance(exc, PermissionError):
return PermissionDeniedError(str(exc), resource=resource)
if isinstance(exc, FileNotFoundError):
- return NotFoundError(resource or str(exc), resource_type)
+ return _not_found_error(resource, resource_type)
if _is_model_api_key_configuration_error(exc):
return FailedPreconditionError(
"Model provider API key is not configured",
@@ -422,7 +426,7 @@ def map_exception(
return UnavailableError("storage backend", reason=str(exc))
if isinstance(exc, AGFSHTTPError):
if exc.status_code == 404 or is_not_found_error(exc):
- return NotFoundError(resource or str(exc), resource_type)
+ return _not_found_error(resource, resource_type)
if exc.status_code == 403:
return PermissionDeniedError(str(exc), resource=resource)
if exc.status_code == 409:
@@ -436,7 +440,7 @@ def map_exception(
if isinstance(exc, AGFSClientError):
message = str(exc)
if is_not_found_error(exc):
- return NotFoundError(resource or message, resource_type)
+ return _not_found_error(resource, resource_type)
if is_invalid_uri_error(exc):
return InvalidURIError(resource or message, message)
lowered = message.lower()
@@ -455,7 +459,7 @@ def map_exception(
message = str(exc)
lowered = message.lower()
if is_not_found_error(exc):
- return NotFoundError(resource or message, resource_type)
+ return _not_found_error(resource, resource_type)
if is_invalid_uri_error(exc):
return InvalidURIError(resource or message, message)
if "permission denied" in lowered or "access denied" in lowered:
diff --git a/openviking/server/routers/pack.py b/openviking/server/routers/pack.py
index 88b26a995..ee0f72f01 100644
--- a/openviking/server/routers/pack.py
+++ b/openviking/server/routers/pack.py
@@ -4,6 +4,7 @@
import os
import tempfile
+from typing import Literal, Optional
from fastapi import APIRouter, Depends, Request
from fastapi.responses import FileResponse
@@ -13,6 +14,7 @@ from starlette.background import BackgroundTask
from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context, require_auth_root_or_admin
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.server.temp_upload_store import TempUploadStore
@@ -32,16 +34,23 @@ class ImportRequest(BaseModel):
Attributes:
temp_file_id: Temporary upload id returned by /api/v1/resources/temp_upload.
parent: Parent URI under which the imported pack will be placed.
- force: Whether to overwrite existing content if needed.
- vectorize: Whether to build vectors for imported content.
+ on_conflict: Conflict policy: fail, overwrite, or skip.
"""
model_config = ConfigDict(extra="forbid")
temp_file_id: str
parent: str
- force: bool = False
- vectorize: bool = True
+ on_conflict: Optional[Literal["fail", "overwrite", "skip"]] = None
+
+
+class RestoreRequest(BaseModel):
+ """Request model for backup restore."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ temp_file_id: str
+ on_conflict: Optional[Literal["fail", "overwrite", "skip"]] = None
@router.post("/export")
@@ -83,10 +92,46 @@ async def export_ovpack(
filename=filename,
background=BackgroundTask(cleanup),
)
- except Exception:
+ except Exception as exc:
# Clean up temp file on error
if os.path.exists(temp_file):
os.unlink(temp_file)
+ mapped = map_exception(exc, resource=uri, resource_type="resource")
+ if mapped is not None:
+ raise mapped from exc
+ raise
+
+
+@require_auth_root_or_admin
+async def backup_ovpack(
+ request: Request,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Back up all public OpenViking scopes as a restore-only .ovpack file."""
+ service = get_service()
+ temp_dir = tempfile.gettempdir()
+ temp_file = os.path.join(temp_dir, f"backup_{os.urandom(16).hex()}.ovpack")
+
+ try:
+ await service.pack.backup_ovpack(temp_file, ctx=ctx)
+
+ def cleanup():
+ if os.path.exists(temp_file):
+ os.unlink(temp_file)
+
+ return FileResponse(
+ path=temp_file,
+ media_type="application/zip",
+ filename="openviking-backup.ovpack",
+ background=BackgroundTask(cleanup),
+ )
+ except Exception as exc:
+ if os.path.exists(temp_file):
+ os.unlink(temp_file)
+ mapped = map_exception(exc, resource="viking://", resource_type="resource")
+ if mapped is not None:
+ raise mapped from exc
raise
@@ -110,8 +155,36 @@ async def import_ovpack(
resolved.local_path,
parent,
ctx=ctx,
- force=body.force,
- vectorize=body.vectorize,
+ on_conflict=body.on_conflict,
+ )
+ except Exception:
+ await store.mark_failed(resolved, ctx)
+ raise
+ else:
+ await store.mark_consumed(resolved, ctx)
+ finally:
+ await resolved.cleanup()
+
+ return Response(status="ok", result={"uri": result})
+
+
[email protected]("/restore")
+@require_auth_root_or_admin
+async def restore_ovpack(
+ request: Request,
+ body: RestoreRequest,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Restore a backup .ovpack file."""
+ service = get_service()
+ store = TempUploadStore.build(request.app.state.config)
+ resolved = await store.resolve_for_consume(body.temp_file_id, ctx)
+
+ try:
+ result = await service.pack.restore_ovpack(
+ resolved.local_path,
+ ctx=ctx,
+ on_conflict=body.on_conflict,
)
except Exception:
await store.mark_failed(resolved, ctx)
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 0caab80e6..dd7ccea5c 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -337,7 +337,10 @@ class OpenVikingService:
privacy_config_service=self._privacy_config_service,
)
self._relation_service.set_viking_fs(self._viking_fs)
- self._pack_service.set_viking_fs(self._viking_fs)
+ self._pack_service.set_dependencies(
+ viking_fs=self._viking_fs,
+ vector_store=self._vikingdb_manager,
+ )
self._search_service.set_viking_fs(self._viking_fs)
self._resource_service.set_dependencies(
vikingdb=self._vikingdb_manager,
diff --git a/openviking/service/pack_service.py b/openviking/service/pack_service.py
index 40969b117..adad20fb8 100644
--- a/openviking/service/pack_service.py
+++ b/openviking/service/pack_service.py
@@ -3,15 +3,17 @@
"""
Pack Service for OpenViking.
-Provides ovpack export/import operations.
+Provides ovpack export/import and backup/restore operations.
"""
from typing import Optional
from openviking.core.uri_validation import validate_viking_uri
from openviking.server.identity import RequestContext
+from openviking.storage.local_fs import backup_ovpack as local_backup_ovpack
from openviking.storage.local_fs import export_ovpack as local_export_ovpack
from openviking.storage.local_fs import import_ovpack as local_import_ovpack
+from openviking.storage.local_fs import restore_ovpack as local_restore_ovpack
from openviking.storage.viking_fs import VikingFS
from openviking_cli.exceptions import NotInitializedError
from openviking_cli.utils import get_logger
@@ -20,15 +22,21 @@ logger = get_logger(__name__)
class PackService:
- """OVPack export/import service."""
+ """OVPack export/import and backup/restore service."""
- def __init__(self, viking_fs: Optional[VikingFS] = None):
+ def __init__(self, viking_fs: Optional[VikingFS] = None, vector_store=None):
self._viking_fs = viking_fs
+ self._vector_store = vector_store
def set_viking_fs(self, viking_fs: VikingFS) -> None:
"""Set VikingFS instance (for deferred initialization)."""
self._viking_fs = viking_fs
+ def set_dependencies(self, viking_fs: VikingFS, vector_store=None) -> None:
+ """Set pack service dependencies."""
+ self._viking_fs = viking_fs
+ self._vector_store = vector_store
+
def _ensure_initialized(self) -> VikingFS:
"""Ensure VikingFS is initialized."""
if not self._viking_fs:
@@ -47,23 +55,37 @@ class PackService:
"""
viking_fs = self._ensure_initialized()
uri = validate_viking_uri(uri)
- return await local_export_ovpack(viking_fs, uri, to, ctx=ctx)
+ return await local_export_ovpack(
+ viking_fs,
+ uri,
+ to,
+ ctx=ctx,
+ vector_store=self._vector_store,
+ )
+
+ async def backup_ovpack(self, to: str, ctx: RequestContext) -> str:
+ """Back up all public OpenViking scopes as a restore-only .ovpack file."""
+ viking_fs = self._ensure_initialized()
+ return await local_backup_ovpack(
+ viking_fs,
+ to,
+ ctx=ctx,
+ vector_store=self._vector_store,
+ )
async def import_ovpack(
self,
file_path: str,
parent: str,
ctx: RequestContext,
- force: bool = False,
- vectorize: bool = True,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import local .ovpack file to specified parent path.
Args:
file_path: Local .ovpack file path
parent: Target parent URI (e.g., viking://user/alice/resources/references/)
- force: Whether to force overwrite existing resources
- vectorize: Whether to trigger vectorization
+ on_conflict: One of "fail", "overwrite", or "skip"
Returns:
Imported root resource URI
@@ -71,5 +93,24 @@ class PackService:
viking_fs = self._ensure_initialized()
parent = validate_viking_uri(parent, field_name="parent")
return await local_import_ovpack(
- viking_fs, file_path, parent, force=force, vectorize=vectorize, ctx=ctx
+ viking_fs,
+ file_path,
+ parent,
+ on_conflict=on_conflict,
+ ctx=ctx,
+ )
+
+ async def restore_ovpack(
+ self,
+ file_path: str,
+ ctx: RequestContext,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore a backup .ovpack file to its original public scope roots."""
+ viking_fs = self._ensure_initialized()
+ return await local_restore_ovpack(
+ viking_fs,
+ file_path,
+ ctx=ctx,
+ on_conflict=on_conflict,
)
diff --git a/openviking/storage/local_fs.py b/openviking/storage/local_fs.py
index 03457b5cf..0731c5ead 100644
--- a/openviking/storage/local_fs.py
+++ b/openviking/storage/local_fs.py
@@ -1,25 +1,88 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
import asyncio
+import hashlib
import json
import os
import re
import zipfile
+from typing import Any, Optional
from openviking.core.namespace import context_type_for_uri
from openviking.resource.watch_storage import is_watch_task_control_uri
from openviking.server.identity import RequestContext
+from openviking.storage.expr import Eq
from openviking.utils.embedding_utils import vectorize_directory_meta, vectorize_file
-from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
+from openviking_cli.exceptions import ConflictError, InvalidArgumentError, NotFoundError
from openviking_cli.utils.logger import get_logger
from openviking_cli.utils.uri import VikingURI
logger = get_logger(__name__)
-_DERIVED_FILENAMES = frozenset({".relations.json"})
+OVPACK_FORMAT_VERSION = 2
+OVPACK_KIND = "openviking.ovpack"
+OVPACK_MANIFEST_FILENAME = ".ovpack_manifest.json"
+OVPACK_MANIFEST_ZIP_LEAF = "_._ovpack_manifest.json"
+OVPACK_ON_CONFLICT_VALUES = frozenset({"fail", "overwrite", "skip"})
+OVPACK_BACKUP_NAME = "openviking-backup"
+OVPACK_BACKUP_TYPE = "backup"
+
+_PUBLIC_SCOPES = ("resources", "user", "agent", "session")
+_IMPORTABLE_SCOPES = frozenset(_PUBLIC_SCOPES)
+_STRUCTURED_IMPORT_SCOPES = frozenset({"user", "agent", "session"})
+_EXCLUDED_FILENAMES = frozenset({".relations.json", OVPACK_MANIFEST_FILENAME})
+_NON_VECTOR_SCOPES = frozenset({"session"})
+_PORTABLE_VECTOR_SCALAR_FIELDS = [
+ "uri",
+ "type",
+ "context_type",
+ "level",
+ "name",
+ "description",
+ "tags",
+ "abstract",
+]
_UNSAFE_PATH_RE = re.compile(r"(^|[\\/])\.\.($|[\\/])")
_DRIVE_RE = re.compile(r"^[A-Za-z]:")
+_SHA256_RE = re.compile(r"^[0-9a-fA-F]{64}$")
+
+
+def _strip_uri_trailing_slash(uri: str) -> str:
+ normalized = VikingURI(uri.strip()).uri
+ return normalized if normalized == "viking://" else normalized.rstrip("/")
+
+
+def _join_uri(base_uri: str, rel_path: str) -> str:
+ base_uri = _strip_uri_trailing_slash(base_uri)
+ if base_uri == "viking://":
+ return f"viking://{rel_path}" if rel_path else base_uri
+ return f"{base_uri}/{rel_path}" if rel_path else base_uri
+
+
+def _rel_path_for_uri(root_uri: str, uri: str) -> str:
+ root_uri = _strip_uri_trailing_slash(root_uri)
+ uri = _strip_uri_trailing_slash(uri)
+ if uri == root_uri:
+ return ""
+ prefix = f"{root_uri}/"
+ return uri[len(prefix) :] if uri.startswith(prefix) else ""
+
+
+def _leaf_name(uri_or_path: str) -> str:
+ return uri_or_path.rstrip("/").split("/")[-1]
+
+
+def _sha256_hex(data: bytes) -> str:
+ return hashlib.sha256(data).hexdigest()
+
+
+def _is_excluded_rel_path(rel_path: str) -> bool:
+ return _leaf_name(rel_path) in _EXCLUDED_FILENAMES
+
+
+def _is_manifest_zip_path(zip_path: str, base_name: str) -> bool:
+ return zip_path == f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}"
def _validate_ovpack_member_path(zip_path: str, base_name: str) -> str:
@@ -59,98 +122,780 @@ def ensure_dir_exists(path: str) -> None:
def get_ovpack_zip_path(base_name: str, rel_path: str) -> str:
- """Generate ZIP internal path from relative path, converting components starting with . to _._"""
+ """Generate ZIP internal path from a Viking relative path."""
+ if not rel_path:
+ return f"{base_name}/"
parts = rel_path.split("/")
- new_parts = []
- for p in parts:
- if p.startswith("."):
- new_parts.append("_._" + p[1:])
- else:
- new_parts.append(p)
- return f"{base_name}/{'/'.join(new_parts)}"
+ escaped = [("_._" + part[1:]) if part.startswith(".") else part for part in parts]
+ return f"{base_name}/{'/'.join(escaped)}"
def get_viking_rel_path_from_zip(zip_path: str) -> str:
- """Restore Viking relative path from ZIP path, converting components starting with _._ back to ."""
- # Remove root directory prefix (base_name/)
+ """Restore Viking relative path from ZIP path."""
parts = zip_path.split("/")
if len(parts) <= 1:
return ""
- # Remove first element (base_name)
rel_parts = parts[1:]
- new_parts = []
- for p in rel_parts:
- if p.startswith("_._"):
- new_parts.append("." + p[3:])
- else:
- new_parts.append(p)
+ restored = [("." + part[3:]) if part.startswith("_._") else part for part in rel_parts]
+ return "/".join(restored)
- return "/".join(new_parts)
+
+def _validate_public_scope(uri: str, *, operation: str, allow_root: bool = False) -> None:
+ parsed = VikingURI(uri)
+ if parsed.uri == "viking://":
+ if allow_root:
+ return
+ raise InvalidArgumentError(f"ovpack {operation} is not supported for root URI")
+ if parsed.scope not in _IMPORTABLE_SCOPES:
+ raise InvalidArgumentError(f"ovpack {operation} is not supported for scope: {parsed.scope}")
def _validate_import_target_uri(uri: str) -> None:
"""Enforce the same target-policy boundary as direct content writes."""
- parsed = VikingURI(uri)
- if parsed.scope not in {"resources", "user", "agent"}:
- raise InvalidArgumentError(f"ovpack import is not supported for scope: {parsed.scope}")
-
- name = uri.rstrip("/").split("/")[-1]
- if name in _DERIVED_FILENAMES:
- raise InvalidArgumentError(f"cannot import derived semantic file: {uri}")
+ _validate_public_scope(uri, operation="import")
+ name = _leaf_name(uri)
+ if name in _EXCLUDED_FILENAMES:
+ raise InvalidArgumentError(f"cannot import internal ovpack file: {uri}")
if is_watch_task_control_uri(uri):
raise InvalidArgumentError(f"cannot import watch task control file: {uri}")
-async def _enqueue_direct_vectorization(viking_fs, uri: str, ctx: RequestContext) -> None:
- entries = await viking_fs.tree(uri, node_limit=100000, level_limit=1000, ctx=ctx)
+def _validate_export_source_uri(uri: str) -> None:
+ _validate_public_scope(uri, operation="export")
+ name = _leaf_name(uri)
+ if name in _EXCLUDED_FILENAMES:
+ raise InvalidArgumentError(f"cannot export internal ovpack file: {uri}")
+ if is_watch_task_control_uri(uri):
+ raise InvalidArgumentError(f"cannot export watch task control file: {uri}")
+
+
+def _base_name_from_entries(infolist: list[zipfile.ZipInfo]) -> str:
+ for info in infolist:
+ filename = info.filename
+ if filename:
+ base_name = filename.replace("\\", "/").split("/")[0]
+ if base_name:
+ return base_name
+ raise ValueError("Could not determine root directory name from ovpack")
+
+
+def _normalize_on_conflict(on_conflict: Optional[str]) -> str:
+ if on_conflict is None:
+ return "fail"
+ if on_conflict not in OVPACK_ON_CONFLICT_VALUES:
+ allowed = ", ".join(sorted(OVPACK_ON_CONFLICT_VALUES))
+ raise InvalidArgumentError(
+ f"Invalid on_conflict value: {on_conflict}. Must be one of: {allowed}"
+ )
+ return on_conflict
+
+
+def _portable_scalars(record: dict[str, Any]) -> dict[str, Any]:
+ return {
+ field: record[field]
+ for field in _PORTABLE_VECTOR_SCALAR_FIELDS
+ if field != "uri" and record.get(field) is not None
+ }
+
+
+def _record_level(record: dict[str, Any], default: int = 2) -> int:
+ try:
+ return int(record.get("level", default))
+ except (TypeError, ValueError):
+ return default
+
+
+async def _call_vector_filter(vector_store, uri: str, ctx: RequestContext) -> list[dict[str, Any]]:
+ if not vector_store or not hasattr(vector_store, "filter"):
+ return []
+
+ kwargs = {
+ "filter": Eq("uri", uri),
+ "limit": 10,
+ "output_fields": _PORTABLE_VECTOR_SCALAR_FIELDS,
+ }
+ try:
+ return await vector_store.filter(**kwargs, ctx=ctx)
+ except TypeError:
+ try:
+ return await vector_store.filter(**kwargs)
+ except Exception as exc:
+ logger.warning(f"Failed to export vector scalars for {uri}: {exc}")
+ except Exception as exc:
+ logger.warning(f"Failed to export vector scalars for {uri}: {exc}")
+ return []
+
+
+async def _read_text_if_exists(viking_fs, uri: str, ctx: RequestContext) -> str:
+ try:
+ if not await viking_fs.exists(uri, ctx=ctx):
+ return ""
+ content = await viking_fs.read_file(uri, ctx=ctx)
+ return content.decode("utf-8") if isinstance(content, bytes) else content
+ except Exception:
+ return ""
+
+
+async def _directory_vector_texts(viking_fs, uri: str, ctx: RequestContext) -> dict[int, str]:
+ abstract = await _read_text_if_exists(viking_fs, f"{uri}/.abstract.md", ctx)
+ overview = await _read_text_if_exists(viking_fs, f"{uri}/.overview.md", ctx)
+ return {0: abstract, 1: overview}
+
+
+async def _manifest_vector_records(
+ viking_fs,
+ vector_store,
+ uri: str,
+ is_dir: bool,
+ ctx: RequestContext,
+) -> list[dict[str, Any]]:
+ records = await _call_vector_filter(vector_store, uri, ctx)
+ records_by_level = {_record_level(record): record for record in records}
+ texts = await _directory_vector_texts(viking_fs, uri, ctx) if is_dir else {}
+
+ manifest_records: list[dict[str, Any]] = []
+ for level in sorted(records_by_level):
+ item = {
+ "level": level,
+ "scalars": _portable_scalars(records_by_level[level]),
+ }
+ text = texts.get(level)
+ if text:
+ item["text"] = text
+ manifest_records.append(item)
+
+ if is_dir:
+ abstract = texts.get(0, "")
+ for level, text in texts.items():
+ if text and level not in records_by_level:
+ manifest_records.append(
+ {
+ "level": level,
+ "text": text,
+ "scalars": {
+ "context_type": context_type_for_uri(uri),
+ "level": level,
+ "abstract": abstract,
+ },
+ }
+ )
+
+ return sorted(manifest_records, key=lambda item: int(item.get("level", 2)))
+
+
+async def _build_manifest(
+ viking_fs,
+ vector_store,
+ root_uri: str,
+ base_name: str,
+ entries: list[dict[str, Any]],
+ ctx: RequestContext,
+ package_type: Optional[str] = None,
+ scopes: Optional[list[str]] = None,
+) -> dict[str, Any]:
+ manifest_entries = [{"path": "", "kind": "directory"}]
+ vectors: dict[str, list[dict[str, Any]]] = {}
+
+ if root_uri != "viking://":
+ root_vectors = await _manifest_vector_records(
+ viking_fs, vector_store, root_uri, is_dir=True, ctx=ctx
+ )
+ if root_vectors:
+ vectors[""] = root_vectors
+
+ for entry in entries:
+ rel_path = entry["rel_path"]
+ is_dir = bool(entry.get("isDir"))
+ manifest_entries.append(
+ {
+ "path": rel_path,
+ "kind": "directory" if is_dir else "file",
+ "size": entry.get("size", 0) if not is_dir else 0,
+ }
+ )
+ records = await _manifest_vector_records(
+ viking_fs,
+ vector_store,
+ _join_uri(root_uri, rel_path),
+ is_dir=is_dir,
+ ctx=ctx,
+ )
+ if records:
+ vectors[rel_path] = records
+
+ root = {
+ "name": base_name,
+ "uri": root_uri,
+ "scope": "root" if root_uri == "viking://" else VikingURI(root_uri).scope,
+ }
+ manifest: dict[str, Any] = {
+ "kind": OVPACK_KIND,
+ "format_version": OVPACK_FORMAT_VERSION,
+ "root": root,
+ "entries": manifest_entries,
+ "vectors": vectors,
+ }
+ if package_type:
+ root["package_type"] = package_type
+ if scopes is not None:
+ manifest["scopes"] = scopes
+ return manifest
+
+
+def _invalid_manifest(message: str, manifest_path: str, **details: Any) -> InvalidArgumentError:
+ return InvalidArgumentError(
+ message,
+ details={"manifest_path": manifest_path, **details},
+ )
+
+
+def _read_manifest(zf: zipfile.ZipFile, base_name: str) -> dict[str, Any]:
+ manifest_path = f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}"
+ try:
+ raw = zf.read(manifest_path)
+ except KeyError:
+ raise _invalid_manifest(
+ "Missing ovpack manifest",
+ manifest_path,
+ hint="Re-export this package with OVPack v2 checksum support before importing.",
+ )
+
+ try:
+ manifest = json.loads(raw.decode("utf-8"))
+ except json.JSONDecodeError as exc:
+ raise _invalid_manifest(
+ "Invalid JSON in ovpack manifest",
+ manifest_path,
+ reason=str(exc),
+ ) from exc
+ if not isinstance(manifest, dict):
+ raise _invalid_manifest(
+ "Invalid ovpack manifest",
+ manifest_path,
+ actual_type=type(manifest).__name__,
+ )
+
+ version = manifest.get("format_version")
+ if version is None:
+ raise _invalid_manifest(
+ "Missing ovpack format_version",
+ manifest_path,
+ field="format_version",
+ )
+ try:
+ version_int = int(version)
+ except (TypeError, ValueError) as exc:
+ raise _invalid_manifest(
+ f"Invalid ovpack format_version {version!r}",
+ manifest_path,
+ field="format_version",
+ value=version,
+ ) from exc
+ if version_int < 1:
+ raise _invalid_manifest(
+ f"Invalid ovpack format_version {version!r}",
+ manifest_path,
+ field="format_version",
+ value=version,
+ )
+ if version_int != OVPACK_FORMAT_VERSION:
+ raise _invalid_manifest(
+ f"Unsupported ovpack format_version {version}; "
+ f"this OpenViking requires {OVPACK_FORMAT_VERSION}",
+ manifest_path,
+ format_version=version_int,
+ supported_format_version=OVPACK_FORMAT_VERSION,
+ )
+ if manifest.get("kind") != OVPACK_KIND:
+ raise _invalid_manifest(
+ "Invalid ovpack manifest kind",
+ manifest_path,
+ expected=OVPACK_KIND,
+ actual=manifest.get("kind"),
+ )
+ return manifest
+
+
+def _manifest_root_uri(manifest: dict[str, Any]) -> str:
+ root = manifest.get("root")
+ if not isinstance(root, dict):
+ return ""
+ uri = root.get("uri")
+ if isinstance(uri, str):
+ try:
+ return _strip_uri_trailing_slash(uri)
+ except Exception:
+ return uri.rstrip("/")
+ return ""
+
+
+def _is_backup_package(manifest: dict[str, Any]) -> bool:
+ root = manifest.get("root")
+ return (
+ isinstance(root, dict)
+ and root.get("package_type") == OVPACK_BACKUP_TYPE
+ and _manifest_root_uri(manifest) == "viking://"
+ )
+
+
+def _is_top_level_scope_package(base_name: str, manifest: dict[str, Any]) -> bool:
+ root_uri = _manifest_root_uri(manifest)
+ return base_name in _IMPORTABLE_SCOPES and root_uri == f"viking://{base_name}"
+
+
+def _resolve_import_root_uri(parent: str, base_name: str, manifest: dict[str, Any]) -> str:
+ if _is_backup_package(manifest):
+ raise InvalidArgumentError(
+ "Backup ovpack packages must be restored with ov restore or the restore API",
+ details={"root": base_name, "parent": parent},
+ )
+
+ if parent == "viking://":
+ if not _is_top_level_scope_package(base_name, manifest):
+ raise InvalidArgumentError(
+ "Only top-level scope ovpack packages can be imported to viking://",
+ details={"root": base_name},
+ )
+ return f"viking://{base_name}"
+
+ if _is_top_level_scope_package(base_name, manifest):
+ raise InvalidArgumentError(
+ "Top-level scope ovpack packages must be imported to viking://",
+ details={"root": base_name, "parent": parent},
+ )
+ return _join_uri(parent, base_name)
+
+
+def _parse_import_uri(uri: str, *, field: str) -> VikingURI:
+ if not uri:
+ raise InvalidArgumentError(f"Missing ovpack {field}")
+ try:
+ return VikingURI(uri)
+ except ValueError as exc:
+ raise InvalidArgumentError(f"Invalid ovpack {field}", details={field: uri}) from exc
+
+
+def _uri_depth(parsed: VikingURI) -> int:
+ return len([part for part in parsed.full_path.split("/") if part])
+
+
+def _validate_import_scope_compatibility(manifest: dict[str, Any], target_root_uri: str) -> None:
+ source_root_uri = _manifest_root_uri(manifest)
+ source = _parse_import_uri(source_root_uri, field="manifest root uri")
+ target = _parse_import_uri(target_root_uri, field="target root uri")
+
+ if source.scope not in _IMPORTABLE_SCOPES:
+ raise InvalidArgumentError(
+ "ovpack import is not supported for source scope",
+ details={"source_scope": source.scope},
+ )
+ if source.scope != target.scope:
+ raise InvalidArgumentError(
+ "ovpack source scope does not match target scope",
+ details={
+ "source_scope": source.scope,
+ "target_scope": target.scope,
+ },
+ )
+ if source.scope in _STRUCTURED_IMPORT_SCOPES and _uri_depth(source) != _uri_depth(target):
+ raise InvalidArgumentError(
+ "ovpack source path is incompatible with target path",
+ details={"source": source_root_uri, "target": target_root_uri},
+ )
+
+
+def _manifest_records_by_level(
+ manifest: dict[str, Any], rel_path: str
+) -> dict[int, dict[str, Any]]:
+ vectors = manifest.get("vectors") if isinstance(manifest, dict) else None
+ records = vectors.get(rel_path, []) if isinstance(vectors, dict) else []
+ if not isinstance(records, list):
+ return {}
+
+ by_level: dict[int, dict[str, Any]] = {}
+ for record in records:
+ if not isinstance(record, dict):
+ continue
+ try:
+ level = int(record.get("level", 2))
+ except (TypeError, ValueError):
+ continue
+ by_level[level] = record
+ return by_level
+
+
+def _manifest_scalar_overrides(
+ manifest: dict[str, Any], rel_path: str
+) -> dict[int, dict[str, Any]]:
+ overrides: dict[int, dict[str, Any]] = {}
+ for level, record in _manifest_records_by_level(manifest, rel_path).items():
+ scalars = record.get("scalars")
+ if isinstance(scalars, dict):
+ overrides[level] = dict(scalars)
+ return overrides
+
+
+def _normalize_sha256(value: Any, *, field: str, path: str | None = None) -> str:
+ if not isinstance(value, str) or not _SHA256_RE.fullmatch(value):
+ details = {"field": field}
+ if path is not None:
+ details["path"] = path
+ raise InvalidArgumentError(f"Invalid ovpack manifest {field}", details=details)
+ return value.lower()
+
+
+def _manifest_entries_by_path(manifest: dict[str, Any]) -> dict[str, dict[str, Any]]:
+ if not isinstance(manifest, dict) or "entries" not in manifest:
+ return {}
+
+ entries = manifest.get("entries")
+ if not isinstance(entries, list):
+ raise InvalidArgumentError("Invalid ovpack manifest: entries must be a list")
+
+ by_path: dict[str, dict[str, Any]] = {}
+ for index, entry in enumerate(entries):
+ if not isinstance(entry, dict):
+ raise InvalidArgumentError(
+ "Invalid ovpack manifest entry",
+ details={"index": index},
+ )
+
+ rel_path = entry.get("path")
+ kind = entry.get("kind")
+ if not isinstance(rel_path, str):
+ raise InvalidArgumentError(
+ "Invalid ovpack manifest entry path",
+ details={"index": index},
+ )
+ if kind not in {"directory", "file"}:
+ raise InvalidArgumentError(
+ "Invalid ovpack manifest entry kind",
+ details={"path": rel_path, "kind": kind},
+ )
+ if rel_path in by_path:
+ raise InvalidArgumentError(
+ "Duplicate ovpack manifest entry",
+ details={"path": rel_path},
+ )
+ by_path[rel_path] = entry
+
+ return by_path
+
+
+def _manifest_content_sha256(file_entries_by_path: dict[str, dict[str, Any]]) -> str:
+ content_entries: list[dict[str, Any]] = []
+ for rel_path, entry in sorted(file_entries_by_path.items()):
+ size = entry.get("size")
+ if not isinstance(size, int) or isinstance(size, bool) or size < 0:
+ raise InvalidArgumentError(
+ "Invalid ovpack manifest file size",
+ details={"path": rel_path, "size": size},
+ )
+ content_entries.append(
+ {
+ "path": rel_path,
+ "size": size,
+ "sha256": _normalize_sha256(entry.get("sha256"), field="sha256", path=rel_path),
+ }
+ )
+
+ payload = json.dumps(
+ content_entries,
+ ensure_ascii=False,
+ sort_keys=True,
+ separators=(",", ":"),
+ ).encode("utf-8")
+ return _sha256_hex(payload)
+
+
+def _zip_file_members_by_path(
+ infolist: list[zipfile.ZipInfo], base_name: str
+) -> dict[str, tuple[zipfile.ZipInfo, str]]:
+ files: dict[str, tuple[zipfile.ZipInfo, str]] = {}
+ for info in infolist:
+ zip_path = info.filename
+ if not zip_path:
+ continue
+ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)
+ if _is_manifest_zip_path(safe_zip_path, base_name) or safe_zip_path.endswith("/"):
+ continue
+
+ rel_path = get_viking_rel_path_from_zip(safe_zip_path)
+ if rel_path in files:
+ raise InvalidArgumentError(
+ "Duplicate ovpack file entry",
+ details={"path": rel_path},
+ )
+ files[rel_path] = (info, safe_zip_path)
+ return files
+
+
+def _zip_directory_members_by_path(infolist: list[zipfile.ZipInfo], base_name: str) -> set[str]:
+ directories: set[str] = set()
+ for info in infolist:
+ zip_path = info.filename
+ if not zip_path:
+ continue
+ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)
+ if not safe_zip_path.endswith("/"):
+ continue
+
+ rel_path = get_viking_rel_path_from_zip(safe_zip_path.rstrip("/"))
+ if rel_path in directories:
+ raise InvalidArgumentError(
+ "Duplicate ovpack directory entry",
+ details={"path": rel_path},
+ )
+ directories.add(rel_path)
+ return directories
+
+
+def _validate_manifest_content(
+ zf: zipfile.ZipFile,
+ manifest: dict[str, Any],
+ infolist: list[zipfile.ZipInfo],
+ base_name: str,
+) -> None:
+ if "entries" not in manifest:
+ raise InvalidArgumentError(
+ "Missing ovpack manifest entries",
+ details={"field": "entries"},
+ )
+
+ manifest_entries = _manifest_entries_by_path(manifest)
+ manifest_files = {
+ rel_path: entry
+ for rel_path, entry in manifest_entries.items()
+ if entry.get("kind") == "file"
+ }
+ manifest_directories = {
+ rel_path for rel_path, entry in manifest_entries.items() if entry.get("kind") == "directory"
+ }
+ zip_files = _zip_file_members_by_path(infolist, base_name)
+ zip_directories = _zip_directory_members_by_path(infolist, base_name)
+
+ missing_files = sorted(set(manifest_files) - set(zip_files))
+ unexpected_files = sorted(set(zip_files) - set(manifest_files))
+ missing_directories = sorted(manifest_directories - zip_directories)
+ unexpected_directories = sorted(zip_directories - manifest_directories)
+ if missing_files or unexpected_files or missing_directories or unexpected_directories:
+ raise InvalidArgumentError(
+ "ovpack entries do not match manifest",
+ details={
+ "missing_files": missing_files,
+ "unexpected_files": unexpected_files,
+ "missing_directories": missing_directories,
+ "unexpected_directories": unexpected_directories,
+ },
+ )
+
+ expected_content_sha256 = manifest.get("content_sha256")
+ if expected_content_sha256 is None:
+ raise InvalidArgumentError(
+ "Missing ovpack manifest content_sha256",
+ details={"field": "content_sha256"},
+ )
+ expected_content_sha256 = _normalize_sha256(
+ expected_content_sha256,
+ field="content_sha256",
+ )
+ actual_content_sha256 = _manifest_content_sha256(manifest_files)
+ if actual_content_sha256 != expected_content_sha256:
+ raise InvalidArgumentError(
+ "ovpack manifest content_sha256 mismatch",
+ details={
+ "expected": expected_content_sha256,
+ "actual": actual_content_sha256,
+ },
+ )
+
+ for rel_path, (_, safe_zip_path) in sorted(zip_files.items()):
+ entry = manifest_files[rel_path]
+ data = zf.read(safe_zip_path)
+
+ expected_size = entry.get("size")
+ if expected_size is not None:
+ if (
+ not isinstance(expected_size, int)
+ or isinstance(expected_size, bool)
+ or expected_size < 0
+ ):
+ raise InvalidArgumentError(
+ "Invalid ovpack manifest file size",
+ details={"path": rel_path, "size": expected_size},
+ )
+ if len(data) != expected_size:
+ raise InvalidArgumentError(
+ "ovpack file size does not match manifest",
+ details={
+ "path": rel_path,
+ "expected": expected_size,
+ "actual": len(data),
+ },
+ )
+
+ expected_sha256 = entry.get("sha256")
+ if expected_sha256 is not None:
+ expected_sha256 = _normalize_sha256(
+ expected_sha256,
+ field="sha256",
+ path=rel_path,
+ )
+ actual_sha256 = _sha256_hex(data)
+ if actual_sha256 != expected_sha256:
+ raise InvalidArgumentError(
+ "ovpack file sha256 does not match manifest",
+ details={
+ "path": rel_path,
+ "expected": expected_sha256,
+ "actual": actual_sha256,
+ },
+ )
+
+
+def _validated_import_members(
+ infolist: list[zipfile.ZipInfo], base_name: str, root_uri: str
+) -> list[tuple[zipfile.ZipInfo, str, str, str]]:
+ members: list[tuple[zipfile.ZipInfo, str, str, str]] = []
+ for info in infolist:
+ zip_path = info.filename
+ if not zip_path:
+ continue
+
+ safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)
+ if _is_manifest_zip_path(safe_zip_path, base_name):
+ members.append((info, safe_zip_path, "manifest", ""))
+ continue
+
+ kind = "directory" if safe_zip_path.endswith("/") else "file"
+ rel_path = get_viking_rel_path_from_zip(
+ safe_zip_path.rstrip("/") if kind == "directory" else safe_zip_path
+ )
+ if root_uri == "viking://" and rel_path == "":
+ members.append((info, safe_zip_path, kind, rel_path))
+ continue
+ target_uri = _join_uri(root_uri, rel_path)
+ _validate_import_target_uri(target_uri)
+ members.append((info, safe_zip_path, kind, rel_path))
+
+ return members
+
+
+async def _root_exists(viking_fs, root_uri: str, ctx: RequestContext) -> bool:
+ try:
+ await viking_fs.ls(root_uri, ctx=ctx)
+ return True
+ except NotFoundError:
+ return False
+ except FileNotFoundError:
+ return False
+
+
+async def _ensure_parent_exists(viking_fs, parent: str, ctx: RequestContext) -> None:
+ try:
+ await viking_fs.stat(parent, ctx=ctx)
+ except Exception:
+ await viking_fs.mkdir(parent, ctx=ctx)
+
+
+async def _remove_existing_root(viking_fs, root_uri: str, ctx: RequestContext) -> None:
+ if not hasattr(viking_fs, "rm"):
+ logger.warning(f"[local_fs] Cannot remove existing resource without rm(): {root_uri}")
+ return
+ try:
+ await viking_fs.rm(root_uri, recursive=True, ctx=ctx)
+ except NotFoundError:
+ return
+ except FileNotFoundError:
+ return
+
+
+async def _existing_scope_roots(
+ viking_fs, scopes: tuple[str, ...], ctx: RequestContext
+) -> list[str]:
+ existing: list[str] = []
+ for scope in scopes:
+ scope_uri = f"viking://{scope}"
+ if await _root_exists(viking_fs, scope_uri, ctx):
+ existing.append(scope_uri)
+ return existing
+
+
+def _exportable_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ return [entry for entry in entries if not _is_excluded_rel_path(entry.get("rel_path", ""))]
+
+
+async def _enqueue_direct_vectorization(
+ viking_fs,
+ uri: str,
+ ctx: RequestContext,
+ manifest: Optional[dict[str, Any]] = None,
+ manifest_path_root_uri: Optional[str] = None,
+) -> None:
+ manifest = manifest or {}
+ manifest_path_root_uri = manifest_path_root_uri or uri
+ entries = await viking_fs.tree(uri, node_limit=None, level_limit=None, ctx=ctx)
dir_uris = {uri}
- file_entries: list[tuple[str, str, str]] = []
+ file_entries: list[tuple[str, str, str, str]] = []
for entry in entries:
entry_uri = entry.get("uri")
if not entry_uri:
continue
+ rel_path = entry.get("rel_path") or _rel_path_for_uri(uri, entry_uri)
+ manifest_rel_path = _rel_path_for_uri(manifest_path_root_uri, entry_uri)
if entry.get("isDir"):
dir_uris.add(entry_uri)
continue
- name = entry.get("name", "")
+ name = entry.get("name", "") or _leaf_name(rel_path)
if name.startswith("."):
continue
- parent_uri = VikingURI(entry_uri).parent.uri
- file_entries.append((entry_uri, parent_uri, name))
+ parent = VikingURI(entry_uri).parent
+ if parent:
+ file_entries.append((entry_uri, parent.uri, name, manifest_rel_path))
async def index_dir(dir_uri: str) -> None:
- abstract_uri = f"{dir_uri}/.abstract.md"
- overview_uri = f"{dir_uri}/.overview.md"
- abstract = ""
- overview = ""
- try:
- if await viking_fs.exists(abstract_uri, ctx=ctx):
- content = await viking_fs.read_file(abstract_uri, ctx=ctx)
- abstract = content.decode("utf-8") if isinstance(content, bytes) else content
- if await viking_fs.exists(overview_uri, ctx=ctx):
- content = await viking_fs.read_file(overview_uri, ctx=ctx)
- overview = content.decode("utf-8") if isinstance(content, bytes) else content
- except Exception:
+ rel_path = _rel_path_for_uri(manifest_path_root_uri, dir_uri)
+ records_by_level = _manifest_records_by_level(manifest, rel_path)
+ scalar_overrides = _manifest_scalar_overrides(manifest, rel_path)
+ abstract = str(records_by_level.get(0, {}).get("text") or "")
+ overview = str(records_by_level.get(1, {}).get("text") or "")
+
+ if not abstract:
+ abstract = await _read_text_if_exists(viking_fs, f"{dir_uri}/.abstract.md", ctx)
+ if not overview:
+ overview = await _read_text_if_exists(viking_fs, f"{dir_uri}/.overview.md", ctx)
+
+ if not abstract and not overview and not scalar_overrides:
return
await vectorize_directory_meta(
- dir_uri, abstract, overview, context_type=context_type_for_uri(dir_uri), ctx=ctx
+ dir_uri,
+ abstract,
+ overview,
+ context_type=context_type_for_uri(dir_uri),
+ ctx=ctx,
+ include_overview=bool(overview),
+ scalar_overrides=scalar_overrides,
)
- async def index_file(file_uri: str, parent_uri: str, name: str) -> None:
+ async def index_file(file_uri: str, parent_uri: str, name: str, rel_path: str) -> None:
+ overrides = _manifest_scalar_overrides(manifest, rel_path)
+ scalar_override = overrides.get(2) or next(iter(overrides.values()), {})
+ summary = str(scalar_override.get("abstract") or "")
await vectorize_file(
file_path=file_uri,
- summary_dict={"name": name},
+ summary_dict={"name": name, "summary": summary},
parent_uri=parent_uri,
context_type=context_type_for_uri(file_uri),
ctx=ctx,
+ scalar_override=scalar_override,
)
await asyncio.gather(*(index_dir(dir_uri) for dir_uri in dir_uris))
await asyncio.gather(
*(
- index_file(file_uri, parent_uri, file_name)
- for file_uri, parent_uri, file_name in file_entries
+ index_file(file_uri, parent_uri, file_name, rel_path)
+ for file_uri, parent_uri, file_name, rel_path in file_entries
)
)
@@ -160,8 +905,7 @@ async def import_ovpack(
file_path: str,
parent: str,
ctx: RequestContext,
- force: bool = False,
- vectorize: bool = True,
+ on_conflict: Optional[str] = None,
) -> str:
"""
Import .ovpack file to the specified parent path.
@@ -170,8 +914,7 @@ async def import_ovpack(
viking_fs: VikingFS instance
file_path: Local .ovpack file path
parent: Target parent URI (e.g., viking://resources/...)
- force: Whether to force overwrite existing resource (default: False)
- vectorize: Whether to trigger vectorization (default: True)
+ on_conflict: One of "fail", "overwrite", or "skip"
Returns:
Root resource URI after import
@@ -179,100 +922,216 @@ async def import_ovpack(
if not os.path.exists(file_path):
raise FileNotFoundError(f"File not found: {file_path}")
- parent = parent.strip().rstrip("/")
-
- try:
- await viking_fs.stat(parent, ctx=ctx)
- except Exception:
- # Parent directory does not exist, create it
- await viking_fs.mkdir(parent, ctx=ctx)
+ parent = _strip_uri_trailing_slash(parent)
+ _validate_public_scope(parent, operation="import", allow_root=True)
+ conflict_action = _normalize_on_conflict(on_conflict)
with zipfile.ZipFile(file_path, "r") as zf:
- # 1. Get root directory name from ZIP and perform initial validation
infolist = zf.infolist()
if not infolist:
raise ValueError("Empty ovpack file")
- # Extract root directory name (assuming first path component is root name)
- first_path = infolist[0].filename
- # Normalize path separators to handle Windows-created ZIPs
- first_path = first_path.replace("\\", "/")
- base_name = first_path.split("/")[0]
- if not base_name:
- raise ValueError("Could not determine root directory name from ovpack")
-
- root_uri = f"{parent}/{base_name}"
+ base_name = _base_name_from_entries(infolist)
+ manifest = _read_manifest(zf, base_name)
+ root_uri = _resolve_import_root_uri(parent, base_name, manifest)
+ _validate_import_scope_compatibility(manifest, root_uri)
_validate_import_target_uri(root_uri)
+ manifest_root = manifest.get("root") if isinstance(manifest.get("root"), dict) else {}
+ if manifest_root.get("name") and manifest_root.get("name") != base_name:
+ logger.warning(
+ f"[local_fs] Manifest root name ({manifest_root.get('name')}) "
+ f"does not match zip root ({base_name})"
+ )
- # 2. Conflict check
- try:
- await viking_fs.ls(root_uri, ctx=ctx)
- if not force:
- raise FileExistsError(
- f"Resource already exists at {root_uri}. Use force=True to overwrite."
- )
- logger.info(f"[local_fs] Overwriting existing resource at {root_uri}")
- except NotFoundError:
- # Path does not exist, safe to import
- pass
+ members = _validated_import_members(infolist, base_name, root_uri)
+ existing_roots = [root_uri] if await _root_exists(viking_fs, root_uri, ctx) else []
- # 3. Validate core metadata _._meta.json (originally .meta.json)
- meta_zip_path = f"{base_name}/_._meta.json"
- try:
- meta_content = zf.read(meta_zip_path)
- meta_data = json.loads(meta_content.decode("utf-8"))
- if "uri" in meta_data and not meta_data["uri"].endswith(base_name):
- logger.warning(
- f"[local_fs] URI in _._meta.json ({meta_data['uri']}) mismatch with base_name ({base_name})"
+ if existing_roots:
+ if conflict_action == "skip":
+ logger.info(f"[local_fs] Skipped existing resource at {root_uri}")
+ return root_uri
+ if conflict_action == "fail":
+ resource = existing_roots[0]
+ raise ConflictError(
+ f"Resource already exists at {resource}. "
+ "Use on_conflict='overwrite' to replace it.",
+ resource=resource,
)
- except KeyError:
- logger.warning(
- f"[local_fs] _._meta.json not found in {file_path}, importing without validation"
- )
- except json.JSONDecodeError:
- raise ValueError(f"Invalid JSON in {meta_zip_path}")
- # 4. Execute import
- for info in infolist:
- zip_path = info.filename
- if not zip_path:
- continue
+ _validate_manifest_content(zf, manifest, infolist, base_name)
+ if parent != "viking://":
+ await _ensure_parent_exists(viking_fs, parent, ctx)
- # Validate before normalization so backslash paths are rejected
- safe_zip_path = _validate_ovpack_member_path(zip_path, base_name)
- # Normalize path separators to handle Windows-created ZIPs
- safe_zip_path = safe_zip_path.replace("\\", "/")
+ for existing_root in existing_roots:
+ logger.info(f"[local_fs] Overwriting existing resource at {existing_root}")
+ await _remove_existing_root(viking_fs, existing_root, ctx)
- # Handle directory entries
- if safe_zip_path.endswith("/"):
- rel_path = get_viking_rel_path_from_zip(safe_zip_path.rstrip("/"))
- target_dir_uri = f"{root_uri}/{rel_path}" if rel_path else root_uri
- await viking_fs.mkdir(target_dir_uri, exist_ok=True, ctx=ctx)
+ for _, safe_zip_path, kind, rel_path in members:
+ if kind == "manifest":
+ continue
+ if kind == "directory":
+ await viking_fs.mkdir(_join_uri(root_uri, rel_path), exist_ok=True, ctx=ctx)
continue
- # Handle file entries
- rel_path = get_viking_rel_path_from_zip(safe_zip_path)
- target_file_uri = f"{root_uri}/{rel_path}" if rel_path else root_uri
- _validate_import_target_uri(target_file_uri)
-
- try:
- data = zf.read(safe_zip_path)
- await viking_fs.write_file_bytes(target_file_uri, data, ctx=ctx)
- except Exception as e:
- logger.error(f"Failed to import {zip_path} to {target_file_uri}: {e}")
- if not force: # In non-force mode, stop on error
- raise e
+ target_file_uri = _join_uri(root_uri, rel_path)
+ data = zf.read(safe_zip_path)
+ await viking_fs.write_file_bytes(target_file_uri, data, ctx=ctx)
logger.info(f"[local_fs] Successfully imported {file_path} to {root_uri}")
- if vectorize:
- await _enqueue_direct_vectorization(viking_fs, root_uri, ctx=ctx)
+ if VikingURI(root_uri).scope not in _NON_VECTOR_SCOPES:
+ await _enqueue_direct_vectorization(viking_fs, root_uri, ctx=ctx, manifest=manifest)
logger.info(f"[local_fs] Enqueued direct vectorization for: {root_uri}")
+ else:
+ logger.info(f"[local_fs] Skipped vectorization for non-vector scope: {root_uri}")
return root_uri
-async def export_ovpack(viking_fs, uri: str, to: str, ctx: RequestContext) -> str:
+async def _backup_entries(viking_fs, ctx: RequestContext) -> list[dict[str, Any]]:
+ entries: list[dict[str, Any]] = []
+ for scope in _PUBLIC_SCOPES:
+ scope_uri = f"viking://{scope}"
+ entries.append(
+ {
+ "rel_path": scope,
+ "uri": scope_uri,
+ "isDir": True,
+ "size": 0,
+ }
+ )
+ try:
+ scope_entries = await viking_fs.tree(
+ scope_uri,
+ show_all_hidden=True,
+ node_limit=None,
+ level_limit=None,
+ ctx=ctx,
+ )
+ except (NotFoundError, FileNotFoundError):
+ continue
+
+ for entry in _exportable_entries(scope_entries):
+ rel_path = entry.get("rel_path", "")
+ if not rel_path:
+ continue
+ scoped_entry = dict(entry)
+ scoped_entry["rel_path"] = f"{scope}/{rel_path}"
+ scoped_entry["uri"] = _join_uri(scope_uri, rel_path)
+ entries.append(scoped_entry)
+ return entries
+
+
+def _backup_scopes_from_manifest(
+ manifest: dict[str, Any], manifest_entries: dict[str, dict[str, Any]]
+) -> tuple[str, ...]:
+ roots = {rel_path.split("/", 1)[0] for rel_path in manifest_entries if rel_path}
+ unexpected = sorted(root for root in roots if root not in _IMPORTABLE_SCOPES)
+ if unexpected:
+ raise InvalidArgumentError(
+ "Backup ovpack contains unsupported roots",
+ details={"roots": unexpected},
+ )
+
+ directory_scope_roots = {
+ rel_path
+ for rel_path, entry in manifest_entries.items()
+ if rel_path in _IMPORTABLE_SCOPES and entry.get("kind") == "directory"
+ }
+ missing_scope_directories = sorted(roots - directory_scope_roots)
+ if missing_scope_directories:
+ raise InvalidArgumentError(
+ "Backup ovpack scope roots must be directory entries",
+ details={"missing_scope_directories": missing_scope_directories},
+ )
+
+ entry_scopes = tuple(scope for scope in _PUBLIC_SCOPES if scope in directory_scope_roots)
+ declared_scopes = manifest.get("scopes")
+ if not isinstance(declared_scopes, list) or any(
+ not isinstance(scope, str) for scope in declared_scopes
+ ):
+ raise InvalidArgumentError(
+ "Invalid backup ovpack scopes",
+ details={"field": "scopes"},
+ )
+ duplicate_scopes = sorted(
+ scope for scope in set(declared_scopes) if declared_scopes.count(scope) > 1
+ )
+ invalid_scopes = sorted(scope for scope in declared_scopes if scope not in _IMPORTABLE_SCOPES)
+ if duplicate_scopes or invalid_scopes:
+ raise InvalidArgumentError(
+ "Invalid backup ovpack scopes",
+ details={
+ "duplicate_scopes": duplicate_scopes,
+ "invalid_scopes": invalid_scopes,
+ },
+ )
+ if set(declared_scopes) != set(entry_scopes):
+ raise InvalidArgumentError(
+ "Backup ovpack scopes do not match entries",
+ details={
+ "declared_scopes": declared_scopes,
+ "entry_scopes": list(entry_scopes),
+ },
+ )
+ return entry_scopes
+
+
+async def _write_ovpack_archive(
+ viking_fs,
+ root_uri: str,
+ to: str,
+ base_name: str,
+ entries: list[dict[str, Any]],
+ manifest: dict[str, Any],
+ ctx: RequestContext,
+) -> str:
+ ensure_dir_exists(to)
+ manifest_entries = _manifest_entries_by_path(manifest)
+ manifest_file_entries = {
+ rel_path: entry
+ for rel_path, entry in manifest_entries.items()
+ if entry.get("kind") == "file"
+ }
+
+ with zipfile.ZipFile(to, "w", zipfile.ZIP_DEFLATED, allowZip64=True) as zf:
+ zf.writestr(base_name + "/", "")
+
+ for entry in entries:
+ rel_path = entry["rel_path"]
+ zip_path = get_ovpack_zip_path(base_name, rel_path)
+
+ if entry.get("isDir"):
+ zf.writestr(zip_path + "/", "")
+ else:
+ full_uri = entry.get("uri") or _join_uri(root_uri, rel_path)
+ try:
+ data = await viking_fs.read_file_bytes(full_uri, ctx=ctx)
+ except Exception as exc:
+ logger.warning(f"Failed to export file {full_uri}: {exc}")
+ raise
+
+ manifest_entry = manifest_file_entries.get(rel_path)
+ if manifest_entry is not None:
+ manifest_entry["size"] = len(data)
+ manifest_entry["sha256"] = _sha256_hex(data)
+ zf.writestr(zip_path, data)
+
+ manifest["content_sha256"] = _manifest_content_sha256(manifest_file_entries)
+ zf.writestr(
+ f"{base_name}/{OVPACK_MANIFEST_ZIP_LEAF}",
+ json.dumps(manifest, ensure_ascii=False, sort_keys=True, indent=2).encode("utf-8"),
+ )
+ return to
+
+
+async def export_ovpack(
+ viking_fs,
+ uri: str,
+ to: str,
+ ctx: RequestContext,
+ vector_store=None,
+) -> str:
"""
Export the specified context path as a .ovpack file.
@@ -280,71 +1139,141 @@ async def export_ovpack(viking_fs, uri: str, to: str, ctx: RequestContext) -> st
viking_fs: VikingFS instance
uri: Viking URI
to: Target file path (can be an existing directory or a path ending with .ovpack)
+ vector_store: Optional vector store used to export portable scalar metadata
Returns:
Exported file path
- Raises:
- ValueError: If export size exceeds limits (65536 files or 2GB total size)
"""
- # Safety limits
- MAX_FILES = 65536
- MAX_TOTAL_SIZE = 2 * 1024 * 1024 * 1024 # 2GB
+ uri = _strip_uri_trailing_slash(uri)
+ _validate_export_source_uri(uri)
- base_name = uri.strip().rstrip("/").split("/")[-1]
- if not base_name:
- base_name = "export"
+ base_name = _leaf_name(uri) or "export"
if os.path.isdir(to):
to = os.path.join(to, f"{base_name}.ovpack")
else:
to = ensure_ovpack_extension(to)
- ensure_dir_exists(to)
+ entries = _exportable_entries(
+ await viking_fs.tree(
+ uri,
+ show_all_hidden=True,
+ node_limit=None,
+ level_limit=None,
+ ctx=ctx,
+ )
+ )
+ manifest = await _build_manifest(viking_fs, vector_store, uri, base_name, entries, ctx)
+ await _write_ovpack_archive(viking_fs, uri, to, base_name, entries, manifest, ctx)
- entries = await viking_fs.tree(uri, show_all_hidden=True, ctx=ctx)
+ logger.info(f"[local_fs] Exported {uri} to {to}")
+ return to
- # Check file count limit
- file_count = sum(1 for entry in entries if not entry.get("isDir"))
- if file_count > MAX_FILES:
- raise ValueError(
- f"Export aborted: too many files ({file_count} files, limit is {MAX_FILES}). "
- f"Please export a smaller directory."
- )
- # Calculate total size and check limit
- total_size = 0
- for entry in entries:
- if not entry.get("isDir"):
- # Get file size from entry if available
- size = entry.get("size", 0)
- total_size += size
+async def backup_ovpack(
+ viking_fs,
+ to: str,
+ ctx: RequestContext,
+ vector_store=None,
+) -> str:
+ """Export all public OpenViking scopes as a restore-only backup package."""
+ base_name = OVPACK_BACKUP_NAME
+ if os.path.isdir(to):
+ to = os.path.join(to, f"{base_name}.ovpack")
+ else:
+ to = ensure_ovpack_extension(to)
- if total_size > MAX_TOTAL_SIZE:
- size_mb = total_size / (1024 * 1024)
- limit_mb = MAX_TOTAL_SIZE / (1024 * 1024)
- raise ValueError(
- f"Export aborted: total size too large ({size_mb:.1f}MB, limit is {limit_mb:.0f}MB). "
- f"Please export a smaller directory."
- )
+ entries = await _backup_entries(viking_fs, ctx)
+ manifest = await _build_manifest(
+ viking_fs,
+ vector_store,
+ "viking://",
+ base_name,
+ entries,
+ ctx,
+ package_type=OVPACK_BACKUP_TYPE,
+ scopes=list(_PUBLIC_SCOPES),
+ )
+ await _write_ovpack_archive(viking_fs, "viking://", to, base_name, entries, manifest, ctx)
- with zipfile.ZipFile(to, "w", zipfile.ZIP_DEFLATED, allowZip64=True) as zf:
- # Write root directory entry
- zf.writestr(base_name + "/", "")
+ logger.info(f"[local_fs] Backed up OpenViking public scopes to {to}")
+ return to
- for entry in entries:
- rel_path = entry["rel_path"]
- zip_path = get_ovpack_zip_path(base_name, rel_path)
- if entry.get("isDir"):
- zf.writestr(zip_path + "/", "")
- else:
- full_uri = f"{uri}/{rel_path}"
- try:
- data = await viking_fs.read_file_bytes(full_uri, ctx=ctx)
- zf.writestr(zip_path, data)
- except Exception as e:
- logger.warning(f"Failed to export file {full_uri}: {e}")
+async def restore_ovpack(
+ viking_fs,
+ file_path: str,
+ ctx: RequestContext,
+ on_conflict: Optional[str] = None,
+) -> str:
+ """Restore a backup package to its original public scope roots."""
+ if not os.path.exists(file_path):
+ raise FileNotFoundError(f"File not found: {file_path}")
- logger.info(f"[local_fs] Exported {uri} to {to}")
- return to
+ conflict_action = _normalize_on_conflict(on_conflict)
+ root_uri = "viking://"
+
+ with zipfile.ZipFile(file_path, "r") as zf:
+ infolist = zf.infolist()
+ if not infolist:
+ raise ValueError("Empty ovpack file")
+
+ base_name = _base_name_from_entries(infolist)
+ manifest = _read_manifest(zf, base_name)
+ if not _is_backup_package(manifest):
+ raise InvalidArgumentError(
+ "Only backup ovpack packages can be restored with ov restore or the restore API",
+ details={"root": base_name},
+ )
+
+ manifest_entries = _manifest_entries_by_path(manifest)
+ backup_scopes = _backup_scopes_from_manifest(manifest, manifest_entries)
+ members = _validated_import_members(infolist, base_name, root_uri)
+ existing_roots = await _existing_scope_roots(viking_fs, backup_scopes, ctx)
+
+ if existing_roots:
+ if conflict_action == "skip":
+ logger.info("[local_fs] Skipped backup restore because target scopes exist")
+ return root_uri
+ if conflict_action == "fail":
+ resource = existing_roots[0]
+ raise ConflictError(
+ f"Resource already exists at {resource}. "
+ "Use on_conflict='overwrite' to replace it.",
+ resource=resource,
+ )
+
+ _validate_manifest_content(zf, manifest, infolist, base_name)
+
+ for existing_root in existing_roots:
+ logger.info(f"[local_fs] Overwriting existing resource at {existing_root}")
+ await _remove_existing_root(viking_fs, existing_root, ctx)
+
+ for _, safe_zip_path, kind, rel_path in members:
+ if kind == "manifest" or rel_path == "":
+ continue
+ if kind == "directory":
+ await viking_fs.mkdir(_join_uri(root_uri, rel_path), exist_ok=True, ctx=ctx)
+ continue
+
+ data = zf.read(safe_zip_path)
+ await viking_fs.write_file_bytes(_join_uri(root_uri, rel_path), data, ctx=ctx)
+
+ logger.info(f"[local_fs] Successfully restored backup {file_path}")
+
+ for scope in backup_scopes:
+ if scope in _NON_VECTOR_SCOPES:
+ logger.info(f"[local_fs] Skipped vectorization for non-vector scope: {scope}")
+ continue
+ scope_uri = f"viking://{scope}"
+ await _enqueue_direct_vectorization(
+ viking_fs,
+ scope_uri,
+ ctx=ctx,
+ manifest=manifest,
+ manifest_path_root_uri=root_uri,
+ )
+ logger.info(f"[local_fs] Enqueued direct vectorization for: {scope_uri}")
+
+ return root_uri
diff --git a/openviking/sync_client.py b/openviking/sync_client.py
index db723f374..6940648fc 100644
--- a/openviking/sync_client.py
+++ b/openviking/sync_client.py
@@ -297,11 +297,37 @@ class SyncOpenViking:
"""Export .ovpack file"""
return run_async(self._async_client.export_ovpack(uri, to))
+ def backup_ovpack(self, to: str) -> str:
+ """Back up public scopes as a restore-only .ovpack file."""
+ return run_async(self._async_client.backup_ovpack(to))
+
def import_ovpack(
- self, file_path: str, target: str, force: bool = False, vectorize: bool = True
+ self,
+ file_path: str,
+ target: str,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import .ovpack file (triggers vectorization by default)"""
- return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))
+ return run_async(
+ self._async_client.import_ovpack(
+ file_path,
+ target,
+ on_conflict=on_conflict,
+ )
+ )
+
+ def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore backup .ovpack file."""
+ return run_async(
+ self._async_client.restore_ovpack(
+ file_path,
+ on_conflict=on_conflict,
+ )
+ )
def close(self) -> None:
"""Close OpenViking and release resources."""
diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.py
index 28b3d8959..b977a611e 100644
--- a/openviking/utils/embedding_utils.py
+++ b/openviking/utils/embedding_utils.py
@@ -9,7 +9,7 @@ Common logic for creating Context objects and enqueuing them to EmbeddingQueue.
import math
import os
from datetime import datetime, timezone
-from typing import Dict, Optional
+from typing import Any, Dict, Optional
from openviking.core.context import Context, ContextLevel, ResourceContentType, Vectorize
from openviking.core.namespace import context_type_for_uri, owner_space_for_uri
@@ -23,6 +23,25 @@ from openviking_cli.utils.config import get_openviking_config
logger = get_logger(__name__)
_EMBEDDING_TRUNCATION_SUFFIX = "\n...(truncated for embedding)"
+_PORTABLE_SCALAR_FIELDS = frozenset(
+ {
+ "type",
+ "level",
+ "name",
+ "description",
+ "tags",
+ "abstract",
+ }
+)
+
+
+def _apply_scalar_overrides(embedding_msg, overrides: Optional[Dict[str, Any]]) -> None:
+ if not embedding_msg or not overrides:
+ return
+ for field in _PORTABLE_SCALAR_FIELDS:
+ value = overrides.get(field)
+ if value is not None:
+ embedding_msg.context_data[field] = value
def _estimate_embedding_input_tokens(text: str) -> int:
@@ -224,6 +243,7 @@ async def vectorize_directory_meta(
ctx: Optional[RequestContext] = None,
semantic_msg_id: Optional[str] = None,
include_overview: bool = True,
+ scalar_overrides: Optional[Dict[int, Dict[str, Any]]] = None,
) -> None:
"""
Vectorize directory metadata (.abstract.md and .overview.md).
@@ -261,6 +281,10 @@ async def vectorize_directory_meta(
)
context_abstract.set_vectorize(Vectorize(text=abstract))
msg_abstract = EmbeddingMsgConverter.from_context(context_abstract)
+ _apply_scalar_overrides(
+ msg_abstract,
+ (scalar_overrides or {}).get(int(ContextLevel.ABSTRACT.value)),
+ )
if msg_abstract:
msg_abstract.semantic_msg_id = semantic_msg_id
try:
@@ -290,6 +314,10 @@ async def vectorize_directory_meta(
)
context_overview.set_vectorize(Vectorize(text=overview))
msg_overview = EmbeddingMsgConverter.from_context(context_overview)
+ _apply_scalar_overrides(
+ msg_overview,
+ (scalar_overrides or {}).get(int(ContextLevel.OVERVIEW.value)),
+ )
if msg_overview:
msg_overview.semantic_msg_id = semantic_msg_id
try:
@@ -314,6 +342,7 @@ async def vectorize_file(
semantic_msg_id: Optional[str] = None,
use_summary: bool = False,
preserve_existing_created_at: bool = False,
+ scalar_override: Optional[Dict[str, Any]] = None,
) -> None:
"""
Vectorize a single file.
@@ -406,6 +435,7 @@ async def vectorize_file(
if not embedding_msg:
return
+ _apply_scalar_overrides(embedding_msg, scalar_override)
embedding_msg.semantic_msg_id = semantic_msg_id
await embedding_queue.enqueue(embedding_msg)
enqueued = True
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index 1e13d6d6b..a25e10282 100644
--- a/openviking_cli/client/base.py
+++ b/openviking_cli/client/base.py
@@ -302,13 +302,30 @@ class BaseClient(ABC):
"""Export as .ovpack file."""
...
+ @abstractmethod
+ async def backup_ovpack(self, to: str) -> str:
+ """Back up public scopes as a restore-only .ovpack file."""
+ ...
+
@abstractmethod
async def import_ovpack(
- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True
+ self,
+ file_path: str,
+ parent: str,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import .ovpack file."""
...
+ @abstractmethod
+ async def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore backup .ovpack file."""
+ ...
+
# ============= Debug =============
@abstractmethod
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index b7018346e..828922707 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -935,20 +935,38 @@ class AsyncHTTPClient(BaseClient):
return str(to_path)
+ async def backup_ovpack(self, to: str) -> str:
+ """Back up public scopes as a restore-only .ovpack file."""
+ to_path = Path(to)
+ if to_path.is_dir():
+ to_path = to_path / "openviking-backup.ovpack"
+ elif not str(to_path).endswith(".ovpack"):
+ to_path = Path(str(to_path) + ".ovpack")
+
+ to_path.parent.mkdir(parents=True, exist_ok=True)
+
+ response = await self._http.post("/api/v1/pack/backup", json={})
+ if not response.is_success:
+ self._handle_response(response)
+
+ with open(to_path, "wb") as f:
+ f.write(response.content)
+
+ return str(to_path)
+
async def import_ovpack(
self,
file_path: str,
parent: str,
- force: bool = False,
- vectorize: bool = True,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import .ovpack file."""
parent = VikingURI.normalize(parent)
request_data = {
"parent": parent,
- "force": force,
- "vectorize": vectorize,
}
+ if on_conflict is not None:
+ request_data["on_conflict"] = on_conflict
file_path_obj = Path(file_path)
if not file_path_obj.exists():
@@ -966,6 +984,32 @@ class AsyncHTTPClient(BaseClient):
result = self._handle_response(response)
return result.get("uri", "")
+ async def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore backup .ovpack file."""
+ request_data = {}
+ if on_conflict is not None:
+ request_data["on_conflict"] = on_conflict
+
+ file_path_obj = Path(file_path)
+ if not file_path_obj.exists():
+ raise FileNotFoundError(f"Local ovpack file not found: {file_path}")
+ if not file_path_obj.is_file():
+ raise ValueError(f"Path {file_path} is not a file")
+
+ temp_file_id = await self._upload_temp_file(file_path)
+ request_data["temp_file_id"] = temp_file_id
+
+ response = await self._http.post(
+ "/api/v1/pack/restore",
+ json=request_data,
+ )
+ result = self._handle_response(response)
+ return result.get("uri", "")
+
# ============= Debug =============
async def health(self) -> bool:
diff --git a/openviking_cli/client/sync_http.py b/openviking_cli/client/sync_http.py
index e1a625bb8..293c900ba 100644
--- a/openviking_cli/client/sync_http.py
+++ b/openviking_cli/client/sync_http.py
@@ -419,11 +419,37 @@ class SyncHTTPClient:
"""
return run_async(self._async_client.export_ovpack(uri, to))
+ def backup_ovpack(self, to: str) -> str:
+ """Back up public scopes as a restore-only .ovpack file."""
+ return run_async(self._async_client.backup_ovpack(to))
+
def import_ovpack(
- self, file_path: str, target: str, force: bool = False, vectorize: bool = True
+ self,
+ file_path: str,
+ target: str,
+ on_conflict: Optional[str] = None,
) -> str:
"""Import .ovpack file."""
- return run_async(self._async_client.import_ovpack(file_path, target, force, vectorize))
+ return run_async(
+ self._async_client.import_ovpack(
+ file_path,
+ target,
+ on_conflict=on_conflict,
+ )
+ )
+
+ def restore_ovpack(
+ self,
+ file_path: str,
+ on_conflict: Optional[str] = None,
+ ) -> str:
+ """Restore backup .ovpack file."""
+ return run_async(
+ self._async_client.restore_ovpack(
+ file_path,
+ on_conflict=on_conflict,
+ )
+ )
# ============= Admin =============
diff --git a/openviking_cli/exceptions.py b/openviking_cli/exceptions.py
index 875e3acb0..9305a2c6d 100644
--- a/openviking_cli/exceptions.py
+++ b/openviking_cli/exceptions.py
@@ -55,10 +55,13 @@ class NotFoundError(OpenVikingError):
"""Resource not found."""
def __init__(self, resource: str, resource_type: str = "resource"):
- message = f"{resource_type.capitalize()} not found: {resource}"
- super().__init__(
- message, code="NOT_FOUND", details={"resource": resource, "type": resource_type}
- )
+ details = {"type": resource_type}
+ if resource:
+ details["resource"] = resource
+ message = f"{resource_type.capitalize()} not found: {resource}"
+ else:
+ message = f"{resource_type.capitalize()} not found"
+ super().__init__(message, code="NOT_FOUND", details=details)
class AlreadyExistsError(OpenVikingError):
diff --git a/tests/README.md b/tests/README.md
index f59f4325a..b1e2ff977 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -122,7 +122,7 @@ Tests for the OpenViking client API (`AsyncOpenViking` / `SyncOpenViking`).
| `test_search.py` | Semantic search | `find()` fast vector search with limit/threshold/target_uri; `search()` with intent analysis and session context |
| `test_relations.py` | Resource linking | `link()` single/multiple URIs with reason; `unlink()` existing/nonexistent; `relations()` query |
| `test_file_operations.py` | File manipulation | `rm()` file/directory with recursive; `mv()` rename/move; `grep()` content search with case sensitivity; `glob()` pattern matching |
-| `test_import_export.py` | Import/Export | `export_ovpack()` file/directory; `import_ovpack()` with force/vectorize options; roundtrip verification |
+| `test_import_export.py` | Import/Export | `export_ovpack()` file/directory; `import_ovpack()` with conflict policy; roundtrip verification |
### server/
diff --git a/tests/api_test/api/client.py b/tests/api_test/api/client.py
index b716a456b..2e883d132 100644
--- a/tests/api_test/api/client.py
+++ b/tests/api_test/api/client.py
@@ -428,13 +428,18 @@ class OpenVikingAPIClient:
return response
def import_ovpack(
- self, file_path: str, parent: str, force: bool = False, vectorize: bool = True
+ self,
+ file_path: str,
+ parent: str,
+ on_conflict: str | None = None,
) -> requests.Response:
endpoint = "/api/v1/pack/import"
url = self._build_url(self.server_url, endpoint)
if not os.path.isfile(file_path):
raise FileNotFoundError(f"Local ovpack file not found: {file_path}")
- payload = {"parent": parent, "force": force, "vectorize": vectorize}
+ payload = {"parent": parent}
+ if on_conflict is not None:
+ payload["on_conflict"] = on_conflict
payload["temp_file_id"] = self._upload_temp_file(file_path)
return self._request_with_retry(
"POST",
diff --git a/tests/client/test_http_client_local_upload.py b/tests/client/test_http_client_local_upload.py
index e08c9357d..f0c5b5e17 100644
--- a/tests/client/test_http_client_local_upload.py
+++ b/tests/client/test_http_client_local_upload.py
@@ -113,12 +113,18 @@ async def test_import_ovpack_uploads_local_file_even_when_url_is_localhost(tmp_p
client._upload_temp_file = fake_upload
client._handle_response = lambda _response: {"uri": "viking://resources/imported"}
- await client.import_ovpack(str(pack_file), parent="viking://resources/")
+ await client.import_ovpack(
+ str(pack_file),
+ parent="viking://resources/",
+ on_conflict="skip",
+ )
call = fake_http.calls[-1]
assert call["path"] == "/api/v1/pack/import"
assert call["json"]["temp_file_id"] == "upload_pack.ovpack"
+ assert call["json"]["on_conflict"] == "skip"
assert "file_path" not in call["json"]
+ assert "force" not in call["json"]
@pytest.mark.asyncio
diff --git a/tests/client/test_import_export.py b/tests/client/test_import_export.py
index e6d28bc9f..ae776529a 100644
--- a/tests/client/test_import_export.py
+++ b/tests/client/test_import_export.py
@@ -3,7 +3,9 @@
"""Import/export tests"""
+import hashlib
import io
+import json
import zipfile
from pathlib import Path
@@ -53,29 +55,27 @@ class TestImportOvpack:
await client.export_ovpack(uri, str(export_path))
# Import to new location
- import_uri = await client.import_ovpack(
- str(export_path), "viking://resources/imported/", vectorize=False
- )
+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/imported/")
assert isinstance(import_uri, str)
assert "imported" in import_uri
- async def test_import_with_force(self, client_with_resource, temp_dir: Path):
- """Test force overwrite import"""
+ async def test_import_with_on_conflict_overwrite(self, client_with_resource, temp_dir: Path):
+ """Test overwrite import."""
client, uri = client_with_resource
# Export first
- export_path = temp_dir / "force_test.ovpack"
+ export_path = temp_dir / "overwrite_test.ovpack"
await client.export_ovpack(uri, str(export_path))
# First import
- await client.import_ovpack(
- str(export_path), "viking://resources/force_test/", vectorize=False
- )
+ await client.import_ovpack(str(export_path), "viking://resources/overwrite_test/")
- # Second force import (overwrite)
+ # Second import overwrites the existing root.
import_uri = await client.import_ovpack(
- str(export_path), "viking://resources/force_test/", force=True, vectorize=False
+ str(export_path),
+ "viking://resources/overwrite_test/",
+ on_conflict="overwrite",
)
assert isinstance(import_uri, str)
@@ -104,9 +104,7 @@ class TestImportOvpack:
await client.rm(original_uri, recursive=True)
# Import
- import_uri = await client.import_ovpack(
- str(export_path), "viking://resources/roundtrip/", vectorize=False
- )
+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/roundtrip/")
# Read imported content
imported_content = ""
@@ -120,8 +118,18 @@ class TestImportOvpack:
@staticmethod
def _build_ovpack(zip_path: Path, entries: dict[str, str]) -> None:
+ manifest = {
+ "kind": "openviking.ovpack",
+ "format_version": 2,
+ "root": {"name": "pkg"},
+ "entries": [{"path": "", "kind": "directory"}],
+ "content_sha256": hashlib.sha256(b"[]").hexdigest(),
+ "vectors": {},
+ }
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as zf:
+ zf.writestr("pkg/", "")
+ zf.writestr("pkg/_._ovpack_manifest.json", json.dumps(manifest))
for name, content in entries.items():
zf.writestr(name, content)
zip_path.write_bytes(buffer.getvalue())
@@ -131,35 +139,30 @@ class TestImportOvpack:
[
(
{
- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',
"pkg/../../escape.txt": "pwned",
},
"Unsafe ovpack entry path",
),
(
{
- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',
"/abs/path.txt": "pwned",
},
"Unsafe ovpack entry path",
),
(
{
- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',
"C:/drive/path.txt": "pwned",
},
"Unsafe ovpack entry path",
),
(
{
- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',
"pkg\\windows\\path.txt": "pwned",
},
"Unsafe ovpack entry path",
),
(
{
- "pkg/_._meta.json": '{"uri": "viking://resources/pkg"}',
"other/file.txt": "pwned",
},
"Invalid ovpack entry root",
@@ -173,6 +176,4 @@ class TestImportOvpack:
self._build_ovpack(ovpack_path, entries)
with pytest.raises(ValueError, match=error_pattern):
- await client.import_ovpack(
- str(ovpack_path), "viking://resources/security/", vectorize=False
- )
+ await client.import_ovpack(str(ovpack_path), "viking://resources/security/")
diff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.py
index 5906af8bb..b14bd417b 100644
--- a/tests/integration/test_full_workflow.py
+++ b/tests/integration/test_full_workflow.py
@@ -180,9 +180,7 @@ class TestImportExportWorkflow:
await client.rm(original_uri, recursive=True)
# 5. Import
- import_uri = await client.import_ovpack(
- str(export_path), "viking://resources/imported/", vectorize=False
- )
+ import_uri = await client.import_ovpack(str(export_path), "viking://resources/imported/")
# 6. Verify content consistency
imported_content = ""
diff --git a/tests/misc/test_ovpack_import_policy.py b/tests/misc/test_ovpack_import_policy.py
index 74335d04e..77f318406 100644
--- a/tests/misc/test_ovpack_import_policy.py
+++ b/tests/misc/test_ovpack_import_policy.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import hashlib
import json
import os
import tempfile
@@ -13,7 +14,7 @@ from pathlib import Path
import pytest
from openviking.server.identity import RequestContext, Role
-from openviking.storage.local_fs import import_ovpack
+from openviking.storage.local_fs import backup_ovpack, export_ovpack, import_ovpack, restore_ovpack
from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
from openviking_cli.session.user_id import UserIdentifier
@@ -22,6 +23,7 @@ class FakeVikingFS:
def __init__(self) -> None:
self.written_files: list[str] = []
self.created_dirs: list[str] = []
+ self.tree_calls: list[str] = []
async def stat(self, uri: str, ctx=None):
return {"uri": uri, "isDir": True}
@@ -35,7 +37,8 @@ class FakeVikingFS:
async def write_file_bytes(self, uri: str, data: bytes, ctx=None):
self.written_files.append(uri)
- async def tree(self, uri: str, node_limit: int = 100000, level_limit: int = 1000, ctx=None):
+ async def tree(self, uri: str, node_limit=None, level_limit=None, ctx=None):
+ self.tree_calls.append(uri)
return []
async def exists(self, uri: str, ctx=None):
@@ -45,6 +48,109 @@ class FakeVikingFS:
raise FileNotFoundError(uri)
+class FakeExportVikingFS:
+ def __init__(self) -> None:
+ self.binary_files = {
+ "viking://resources/demo/notes.txt": b"hello",
+ }
+ self.text_files = {
+ "viking://resources/demo/.abstract.md": "root abstract",
+ "viking://resources/demo/.overview.md": "root overview",
+ }
+
+ async def tree(
+ self,
+ uri: str,
+ show_all_hidden: bool = False,
+ node_limit=None,
+ level_limit=None,
+ ctx=None,
+ ):
+ assert uri == "viking://resources/demo"
+ assert show_all_hidden is True
+ assert node_limit is None
+ assert level_limit is None
+ return [
+ {
+ "rel_path": ".overview.md",
+ "uri": "viking://resources/demo/.overview.md",
+ "isDir": False,
+ "size": 13,
+ },
+ {
+ "rel_path": "notes.txt",
+ "uri": "viking://resources/demo/notes.txt",
+ "isDir": False,
+ "size": 5,
+ },
+ ]
+
+ async def exists(self, uri: str, ctx=None):
+ return uri in self.text_files
+
+ async def read_file(self, uri: str, ctx=None):
+ return self.text_files[uri]
+
+ async def read_file_bytes(self, uri: str, ctx=None):
+ if uri in self.text_files:
+ return self.text_files[uri].encode("utf-8")
+ return self.binary_files[uri]
+
+
+class FakeBackupVikingFS:
+ def __init__(self) -> None:
+ self.binary_files = {
+ "viking://resources/README.md": b"hello",
+ "viking://session/sess_1/.meta.json": b'{"session_id":"sess_1"}',
+ }
+
+ async def tree(
+ self,
+ uri: str,
+ show_all_hidden: bool = False,
+ node_limit=None,
+ level_limit=None,
+ ctx=None,
+ ):
+ assert show_all_hidden is True
+ assert node_limit is None
+ assert level_limit is None
+ if uri == "viking://resources":
+ return [
+ {
+ "rel_path": "README.md",
+ "uri": "viking://resources/README.md",
+ "isDir": False,
+ "size": 5,
+ }
+ ]
+ if uri == "viking://session":
+ return [
+ {
+ "rel_path": "sess_1",
+ "uri": "viking://session/sess_1",
+ "isDir": True,
+ "size": 0,
+ },
+ {
+ "rel_path": "sess_1/.meta.json",
+ "uri": "viking://session/sess_1/.meta.json",
+ "isDir": False,
+ "size": 23,
+ },
+ ]
+ return []
+
+ async def exists(self, uri: str, ctx=None):
+ return False
+
+ async def read_file(self, uri: str, ctx=None):
+ raise FileNotFoundError(uri)
+
+ async def read_file_bytes(self, uri: str, ctx=None):
+ return self.binary_files[uri]
+
+
@pytest.fixture
def request_ctx() -> RequestContext:
return RequestContext(user=UserIdentifier("acct", "alice", "agent1"), role=Role.USER)
@@ -67,8 +173,137 @@ def _write_ovpack(path: Path, entries: dict[str, str]) -> None:
zf.writestr(name, content)
+def _content_sha256(entries: list[dict[str, object]]) -> str:
+ payload = json.dumps(
+ entries,
+ ensure_ascii=False,
+ sort_keys=True,
+ separators=(",", ":"),
+ ).encode("utf-8")
+ return hashlib.sha256(payload).hexdigest()
+
+
+def _manifest_for_files(root_name: str, files: dict[str, str]) -> dict[str, object]:
+ entries: list[dict[str, object]] = [{"path": "", "kind": "directory"}]
+ content_entries: list[dict[str, object]] = []
+ for rel_path, content in sorted(files.items()):
+ data = content.encode("utf-8")
+ file_entry = {
+ "path": rel_path,
+ "kind": "file",
+ "size": len(data),
+ "sha256": hashlib.sha256(data).hexdigest(),
+ }
+ entries.append(file_entry)
+ content_entries.append(
+ {
+ "path": rel_path,
+ "size": file_entry["size"],
+ "sha256": file_entry["sha256"],
+ }
+ )
+
+ return {
+ "kind": "openviking.ovpack",
+ "format_version": 2,
+ "root": {
+ "name": root_name,
+ "uri": f"viking://resources/{root_name}",
+ "scope": "resources",
+ },
+ "entries": entries,
+ "content_sha256": _content_sha256(content_entries),
+ "vectors": {},
+ }
+
+
+def _write_ovpack_with_manifest(
+ path: Path,
+ root_name: str,
+ files: dict[str, str],
+ *,
+ manifest: dict[str, object] | None = None,
+) -> None:
+ manifest = manifest or _manifest_for_files(root_name, files)
+ entries = {
+ f"{root_name}/": "",
+ f"{root_name}/_._ovpack_manifest.json": json.dumps(manifest),
+ }
+ entries.update({f"{root_name}/{rel_path}": content for rel_path, content in files.items()})
+ _write_ovpack(path, entries)
+
+
+async def test_export_ovpack_writes_v2_manifest_with_semantic_sidecars(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ await export_ovpack(
+ FakeExportVikingFS(),
+ "viking://resources/demo",
+ str(temp_ovpack_path),
+ ctx=request_ctx,
+ )
+
+ with zipfile.ZipFile(temp_ovpack_path, "r") as zf:
+ names = set(zf.namelist())
+ manifest = json.loads(zf.read("demo/_._ovpack_manifest.json").decode("utf-8"))
+
+ assert "demo/notes.txt" in names
+ assert "demo/_._overview.md" in names
+ assert manifest["format_version"] == 2
+ assert manifest["kind"] == "openviking.ovpack"
+ note_entry = next(entry for entry in manifest["entries"] if entry["path"] == "notes.txt")
+ note_sha256 = hashlib.sha256(b"hello").hexdigest()
+ assert note_entry["size"] == 5
+ assert note_entry["sha256"] == note_sha256
+ overview_entry = next(entry for entry in manifest["entries"] if entry["path"] == ".overview.md")
+ overview_sha256 = hashlib.sha256(b"root overview").hexdigest()
+ assert overview_entry["sha256"] == overview_sha256
+ assert manifest["content_sha256"] == _content_sha256(
+ [
+ {"path": ".overview.md", "size": 13, "sha256": overview_sha256},
+ {"path": "notes.txt", "size": 5, "sha256": note_sha256},
+ ]
+ )
+ assert manifest["vectors"][""][0]["text"] == "root abstract"
+
+
@pytest.mark.asyncio
-async def test_import_ovpack_rejects_derived_semantic_files(
+async def test_backup_restore_contract(temp_ovpack_path: Path, request_ctx: RequestContext):
+ await backup_ovpack(
+ FakeBackupVikingFS(),
+ str(temp_ovpack_path),
+ ctx=request_ctx,
+ )
+
+ with zipfile.ZipFile(temp_ovpack_path, "r") as zf:
+ names = set(zf.namelist())
+ manifest = json.loads(zf.read("openviking-backup/_._ovpack_manifest.json").decode("utf-8"))
+
+ assert "openviking-backup/resources/README.md" in names
+ assert "openviking-backup/session/sess_1/_._meta.json" in names
+ assert manifest["root"] == {
+ "name": "openviking-backup",
+ "uri": "viking://",
+ "scope": "root",
+ "package_type": "backup",
+ }
+ assert manifest["scopes"] == ["resources", "user", "agent", "session"]
+
+ with pytest.raises(InvalidArgumentError, match=r"must be restored"):
+ await import_ovpack(FakeVikingFS(), str(temp_ovpack_path), "viking://", request_ctx)
+
+ fake_fs = FakeVikingFS()
+ assert await restore_ovpack(fake_fs, str(temp_ovpack_path), request_ctx) == "viking://"
+ assert fake_fs.written_files == [
+ "viking://resources/README.md",
+ "viking://session/sess_1/.meta.json",
+ ]
+ assert fake_fs.tree_calls == ["viking://resources", "viking://user", "viking://agent"]
+
+
+async def test_import_legacy_ovpack_without_manifest_is_rejected(
temp_ovpack_path: Path, request_ctx: RequestContext
):
_write_ovpack(
@@ -80,36 +315,148 @@ async def test_import_ovpack_rejects_derived_semantic_files(
)
fake_fs = FakeVikingFS()
- with pytest.raises(
- InvalidArgumentError,
- match=r"cannot import derived semantic file: viking://resources/demo/\.overview\.md",
- ):
- await import_ovpack(
- fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx, vectorize=False
- )
+ with pytest.raises(InvalidArgumentError, match=r"Missing ovpack manifest"):
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
assert fake_fs.written_files == []
@pytest.mark.asyncio
-async def test_import_ovpack_rejects_session_scope_targets(
+async def test_import_ovpack_rejects_manifest_file_hash_mismatch(
temp_ovpack_path: Path, request_ctx: RequestContext
):
+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})
+ _write_ovpack_with_manifest(
+ temp_ovpack_path,
+ "demo",
+ {"notes.txt": "jello"},
+ manifest=manifest,
+ )
+ fake_fs = FakeVikingFS()
+
+ with pytest.raises(InvalidArgumentError, match=r"sha256 does not match manifest"):
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
+
+ assert fake_fs.written_files == []
+
+
+async def test_import_ovpack_rejects_legacy_manifest_version(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})
+ manifest["format_version"] = 1
+ _write_ovpack_with_manifest(temp_ovpack_path, "demo", {"notes.txt": "hello"}, manifest=manifest)
+ fake_fs = FakeVikingFS()
+
+ with pytest.raises(InvalidArgumentError, match=r"Unsupported ovpack format_version 1"):
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
+
+ assert fake_fs.written_files == []
+
+
+async def test_import_ovpack_rejects_manifest_unexpected_directory(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})
_write_ovpack(
temp_ovpack_path,
{
- "victim/_._meta.json": json.dumps({"session_id": "victim"}),
- "victim/messages.jsonl": '{"id":"msg_attacker","role":"user","parts":[{"type":"text","text":"forged"}],"created_at":"2026-01-01T00:00:00Z"}\n',
+ "demo/": "",
+ "demo/_._ovpack_manifest.json": json.dumps(manifest),
+ "demo/notes.txt": "hello",
+ "demo/empty/": "",
},
)
fake_fs = FakeVikingFS()
- with pytest.raises(
- InvalidArgumentError,
- match=r"ovpack import is not supported for scope: session",
- ):
+ with pytest.raises(InvalidArgumentError, match=r"entries do not match manifest") as exc_info:
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
+
+ assert exc_info.value.details["unexpected_directories"] == ["empty"]
+ assert fake_fs.written_files == []
+
+
+async def test_import_ovpack_restores_session_without_vectorization(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ files = {
+ ".meta.json": json.dumps({"session_id": "victim"}),
+ "messages.jsonl": '{"id":"msg_1","role":"user","parts":[{"type":"text","text":"hi"}]}\n',
+ }
+ manifest = _manifest_for_files("victim", files)
+ manifest["root"] = {
+ "name": "victim",
+ "uri": "viking://session/victim",
+ "scope": "session",
+ }
+ _write_ovpack_with_manifest(
+ temp_ovpack_path,
+ "victim",
+ files,
+ manifest=manifest,
+ )
+ fake_fs = FakeVikingFS()
+
+ result = await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://session", request_ctx)
+
+ assert result == "viking://session/victim"
+ assert fake_fs.written_files == [
+ "viking://session/victim/.meta.json",
+ "viking://session/victim/messages.jsonl",
+ ]
+ assert fake_fs.tree_calls == []
+
+ invalid_fs = FakeVikingFS()
+ with pytest.raises(InvalidArgumentError, match=r"source scope does not match target scope"):
+ await import_ovpack(invalid_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
+ with pytest.raises(InvalidArgumentError, match=r"source path is incompatible"):
await import_ovpack(
- fake_fs, str(temp_ovpack_path), "viking://session/default", request_ctx, vectorize=False
+ invalid_fs,
+ str(temp_ovpack_path),
+ "viking://session/victim",
+ request_ctx,
)
+ assert invalid_fs.written_files == []
+
+
+async def test_import_ovpack_rejects_scope_mismatch(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ manifest = _manifest_for_files("demo", {"notes.txt": "hello"})
+ _write_ovpack_with_manifest(temp_ovpack_path, "demo", {"notes.txt": "hello"}, manifest=manifest)
+ fake_fs = FakeVikingFS()
+
+ with pytest.raises(InvalidArgumentError, match=r"source scope does not match target scope"):
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://session", request_ctx)
assert fake_fs.written_files == []
+
+
+async def test_import_top_level_scope_package_requires_root_target(
+ temp_ovpack_path: Path, request_ctx: RequestContext
+):
+ manifest = _manifest_for_files("resources", {"README.md": "hello"})
+ manifest["root"] = {
+ "name": "resources",
+ "uri": "viking://resources",
+ "scope": "resources",
+ }
+ _write_ovpack_with_manifest(
+ temp_ovpack_path,
+ "resources",
+ {"README.md": "hello"},
+ manifest=manifest,
+ )
+ fake_fs = FakeVikingFS()
+
+ with pytest.raises(InvalidArgumentError, match=r"must be imported to viking://"):
+ await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://resources", request_ctx)
+
+ assert await import_ovpack(fake_fs, str(temp_ovpack_path), "viking://", request_ctx) == (
+ "viking://resources"
+ )
diff --git a/tests/server/conftest.py b/tests/server/conftest.py
index 0bb79148c..22ca34a99 100644
--- a/tests/server/conftest.py
+++ b/tests/server/conftest.py
@@ -32,6 +32,7 @@ from openviking_cli.utils.config.vlm_config import VLMConfig
PROJECT_ROOT = Path(__file__).parent.parent.parent
TEST_TMP_DIR = PROJECT_ROOT / "test_data" / "tmp_server"
+SDK_ROOT_API_KEY = "test-root-api-key"
# ---------------------------------------------------------------------------
# Sample data
@@ -51,7 +52,7 @@ This is a sample markdown document for server testing.
def _install_fake_embedder(monkeypatch):
"""Use an in-process fake embedder so server tests never hit external APIs."""
- dimension = 2048
+ dimension = 1024
class FakeEmbedder(DenseEmbedderBase):
def __init__(self):
@@ -119,10 +120,16 @@ def upload_temp_dir(temp_dir: Path, monkeypatch) -> Path:
monkeypatch.setattr(
"openviking.server.routers.resources.get_openviking_config",
lambda: config,
+ raising=False,
)
monkeypatch.setattr(
"openviking.server.routers.pack.get_openviking_config",
lambda: config,
+ raising=False,
+ )
+ monkeypatch.setattr(
+ "openviking.server.temp_upload_store.get_openviking_config",
+ lambda: config,
)
return temp_dir
@@ -195,7 +202,7 @@ async def running_server(temp_dir: Path, monkeypatch):
await svc.initialize()
svc.viking_fs.query_embedder = fake_embedder_cls()
- config = ServerConfig()
+ config = ServerConfig(root_api_key=SDK_ROOT_API_KEY)
fastapi_app = create_app(config=config, service=svc)
# Find a free port
@@ -217,6 +224,13 @@ async def running_server(temp_dir: Path, monkeypatch):
except Exception:
time.sleep(0.1)
+ for _ in range(50):
+ if getattr(fastapi_app.state, "api_key_manager", None) is not None:
+ break
+ time.sleep(0.1)
+ else:
+ raise RuntimeError("APIKeyManager did not initialize for SDK server test")
+
yield port, svc
server.should_exit = True
diff --git a/tests/server/ovpack_test_helpers.py b/tests/server/ovpack_test_helpers.py
new file mode 100644
index 000000000..f9c4b15f4
--- /dev/null
+++ b/tests/server/ovpack_test_helpers.py
@@ -0,0 +1,62 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""OVPack fixtures for server tests."""
+
+import hashlib
+import io
+import json
+import zipfile
+
+
+def _content_sha256(entries: list[dict[str, object]]) -> str:
+ payload = json.dumps(
+ entries,
+ ensure_ascii=False,
+ sort_keys=True,
+ separators=(",", ":"),
+ ).encode("utf-8")
+ return hashlib.sha256(payload).hexdigest()
+
+
+def build_ovpack_bytes(
+ root_name: str = "pkg",
+ files: dict[str, bytes] | None = None,
+) -> bytes:
+ files = files or {"content.md": b"# Demo\n"}
+ manifest_entries: list[dict[str, object]] = [{"path": "", "kind": "directory"}]
+ content_entries: list[dict[str, object]] = []
+
+ for rel_path, content in sorted(files.items()):
+ file_sha256 = hashlib.sha256(content).hexdigest()
+ file_entry = {
+ "path": rel_path,
+ "kind": "file",
+ "size": len(content),
+ "sha256": file_sha256,
+ }
+ manifest_entries.append(file_entry)
+ content_entries.append(
+ {
+ "path": rel_path,
+ "size": file_entry["size"],
+ "sha256": file_entry["sha256"],
+ }
+ )
+
+ manifest = {
+ "kind": "openviking.ovpack",
+ "format_version": 2,
+ "root": {"name": root_name},
+ "entries": manifest_entries,
+ "content_sha256": _content_sha256(content_entries),
+ "vectors": {},
+ }
+
+ buffer = io.BytesIO()
+ with zipfile.ZipFile(buffer, "w") as zf:
+ zf.writestr(f"{root_name}/", "")
+ zf.writestr(f"{root_name}/_._ovpack_manifest.json", json.dumps(manifest))
+ for rel_path, content in files.items():
+ zf.writestr(f"{root_name}/{rel_path}", content)
+ return buffer.getvalue()
diff --git a/tests/server/test_api_local_input_security.py b/tests/server/test_api_local_input_security.py
index f3c98914c..fffcc8292 100644
--- a/tests/server/test_api_local_input_security.py
+++ b/tests/server/test_api_local_input_security.py
@@ -3,9 +3,7 @@
"""Security tests for HTTP server local input handling."""
-import io
import threading
-import zipfile
from http.server import BaseHTTPRequestHandler, HTTPServer
import httpx
@@ -14,6 +12,12 @@ import pytest
from openviking.parse.parsers.html import URLTypeDetector
from openviking.utils.network_guard import ensure_public_remote_target
from openviking_cli.exceptions import PermissionDeniedError
+from tests.server.ovpack_test_helpers import build_ovpack_bytes
+
+
+def _allow_admin_api_in_dev_mode(client: httpx.AsyncClient) -> None:
+ # Admin routes require the app to have an API key manager, even in dev-mode tests.
+ client._transport.app.state.api_key_manager = object()
async def test_add_skill_accepts_temp_uploaded_file(
@@ -57,7 +61,9 @@ async def test_add_skill_rejects_legacy_temp_path_field(client: httpx.AsyncClien
"/api/v1/skills",
json={"temp_path": "upload_skill.md"},
)
- assert resp.status_code == 422
+ assert resp.status_code == 400
+ body = resp.json()
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
async def test_add_skill_accepts_raw_skill_content(client: httpx.AsyncClient):
@@ -79,14 +85,6 @@ description: inline
assert body["result"]["uri"].startswith("viking://agent/default/skills/")
-def _build_ovpack_bytes() -> bytes:
- buffer = io.BytesIO()
- with zipfile.ZipFile(buffer, "w") as zf:
- zf.writestr("pkg/_._meta.json", '{"uri": "viking://resources/pkg"}')
- zf.writestr("pkg/content.md", "# Demo\n")
- return buffer.getvalue()
-
-
@pytest.fixture
def loopback_http_url():
body = b"<html><body>loopback secret</body></html>"
@@ -125,15 +123,15 @@ async def test_import_ovpack_accepts_temp_uploaded_file(
client: httpx.AsyncClient,
upload_temp_dir,
):
+ _allow_admin_api_in_dev_mode(client)
ovpack_file = upload_temp_dir / "demo.ovpack"
- ovpack_file.write_bytes(_build_ovpack_bytes())
+ ovpack_file.write_bytes(build_ovpack_bytes())
resp = await client.post(
"/api/v1/pack/import",
json={
"temp_file_id": ovpack_file.name,
"parent": "viking://resources/imported",
- "vectorize": False,
},
)
assert resp.status_code == 200
@@ -142,16 +140,51 @@ async def test_import_ovpack_accepts_temp_uploaded_file(
assert body["result"]["uri"].startswith("viking://resources/imported/")
+async def test_import_ovpack_conflict_returns_structured_conflict(
+ client: httpx.AsyncClient,
+ upload_temp_dir,
+):
+ _allow_admin_api_in_dev_mode(client)
+ ovpack_file = upload_temp_dir / "demo_conflict.ovpack"
+ ovpack_file.write_bytes(build_ovpack_bytes())
+
+ first = await client.post(
+ "/api/v1/pack/import",
+ json={
+ "temp_file_id": ovpack_file.name,
+ "parent": "viking://resources/imported",
+ },
+ )
+ assert first.status_code == 200
+
+ ovpack_file.write_bytes(build_ovpack_bytes())
+ resp = await client.post(
+ "/api/v1/pack/import",
+ json={
+ "temp_file_id": ovpack_file.name,
+ "parent": "viking://resources/imported",
+ },
+ )
+
+ assert resp.status_code == 409
+ body = resp.json()
+ assert body["status"] == "error"
+ assert body["error"]["code"] == "CONFLICT"
+ assert "Use on_conflict='overwrite'" in body["error"]["message"]
+ assert body["error"]["details"]["resource"] == "viking://resources/imported/pkg"
+
+
async def test_import_ovpack_rejects_direct_file_path_field(client: httpx.AsyncClient):
resp = await client.post(
"/api/v1/pack/import",
json={
"file_path": "/tmp/demo.ovpack",
"parent": "viking://resources/imported",
- "vectorize": False,
},
)
- assert resp.status_code == 422
+ assert resp.status_code == 400
+ body = resp.json()
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
async def test_import_ovpack_rejects_legacy_temp_path_field(client: httpx.AsyncClient):
@@ -160,10 +193,29 @@ async def test_import_ovpack_rejects_legacy_temp_path_field(client: httpx.AsyncC
json={
"temp_path": "upload_pack.ovpack",
"parent": "viking://resources/imported",
+ },
+ )
+ assert resp.status_code == 400
+ body = resp.json()
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
+
+
+async def test_import_ovpack_rejects_removed_fields(client: httpx.AsyncClient):
+ resp = await client.post(
+ "/api/v1/pack/import",
+ json={
+ "temp_file_id": "demo.ovpack",
+ "parent": "viking://resources/imported",
"vectorize": False,
+ "force": True,
},
)
- assert resp.status_code == 422
+ assert resp.status_code == 400
+ body = resp.json()
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
+ validation_errors = body["error"]["details"]["validation_errors"]
+ assert any("vectorize" in error["loc"] for error in validation_errors)
+ assert any("force" in error["loc"] for error in validation_errors)
async def test_import_ovpack_rejects_forged_temp_file_id(
@@ -171,14 +223,13 @@ async def test_import_ovpack_rejects_forged_temp_file_id(
upload_temp_dir,
):
outside_file = upload_temp_dir.parent / "outside.ovpack"
- outside_file.write_bytes(_build_ovpack_bytes())
+ outside_file.write_bytes(build_ovpack_bytes())
resp = await client.post(
"/api/v1/pack/import",
json={
"temp_file_id": "../outside.ovpack",
"parent": "viking://resources/imported",
- "vectorize": False,
},
)
assert resp.status_code == 403
@@ -192,7 +243,9 @@ async def test_add_resource_rejects_legacy_temp_path_field(client: httpx.AsyncCl
"/api/v1/resources",
json={"temp_path": "upload_resource.md", "reason": "legacy field"},
)
- assert resp.status_code == 422
+ assert resp.status_code == 400
+ body = resp.json()
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
async def test_add_resource_rejects_loopback_remote_url(client: httpx.AsyncClient):
diff --git a/tests/server/test_http_client_sdk.py b/tests/server/test_http_client_sdk.py
index 9d17a17e4..0d97e1690 100644
--- a/tests/server/test_http_client_sdk.py
+++ b/tests/server/test_http_client_sdk.py
@@ -4,8 +4,6 @@
"""SDK tests using AsyncHTTPClient against a real uvicorn server."""
import asyncio
-import io
-import zipfile
import httpx
import pytest
@@ -13,7 +11,8 @@ import pytest_asyncio
from openviking_cli.client.http import AsyncHTTPClient
from openviking_cli.exceptions import ConflictError, FailedPreconditionError, ProcessingError
-from tests.server.conftest import SAMPLE_MD_CONTENT, TEST_TMP_DIR
+from tests.server.conftest import SAMPLE_MD_CONTENT, SDK_ROOT_API_KEY, TEST_TMP_DIR
+from tests.server.ovpack_test_helpers import build_ovpack_bytes
@pytest_asyncio.fixture()
@@ -22,6 +21,9 @@ async def http_client(running_server):
port, svc = running_server
client = AsyncHTTPClient(
url=f"http://127.0.0.1:{port}",
+ api_key=SDK_ROOT_API_KEY,
+ account="default",
+ user="sdk_test_user",
)
await client.initialize()
yield client, svc
@@ -114,25 +116,16 @@ description: SDK localhost upload test
assert result["uri"].startswith("viking://agent/default/skills/")
-def _build_ovpack_bytes() -> bytes:
- buffer = io.BytesIO()
- with zipfile.ZipFile(buffer, "w") as zf:
- zf.writestr("pkg/_._meta.json", '{"uri": "viking://resources/pkg"}')
- zf.writestr("pkg/content.md", "# Demo\n")
- return buffer.getvalue()
-
-
async def test_sdk_import_ovpack_from_local_file(http_client):
client, _ = http_client
f = TEST_TMP_DIR / "sdk_import.ovpack"
f.parent.mkdir(parents=True, exist_ok=True)
- f.write_bytes(_build_ovpack_bytes())
+ f.write_bytes(build_ovpack_bytes())
uri = await client.import_ovpack(
str(f),
parent="viking://resources/imported/",
- force=True,
- vectorize=False,
+ on_conflict="overwrite",
)
assert uri.startswith("viking://resources/imported/")