Skip to content

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

fix(ovpack): skip missing semantic sidecars (#2265)

Qin Haojief2f8076f3193
diff --git a/openviking/storage/ovpack/operations.py b/openviking/storage/ovpack/operations.py
index 34c9a0d79..5e37c6037 100644
--- a/openviking/storage/ovpack/operations.py
+++ b/openviking/storage/ovpack/operations.py
@@ -69,6 +69,8 @@ from openviking_cli.utils.uri import VikingURI
logger = get_logger(__name__)
+OPTIONAL_SEMANTIC_SIDECARS = frozenset({".abstract.md", ".overview.md"})
+
def _index_records_by_level(
index_records: list[dict[str, Any]], rel_path: str
@@ -148,6 +150,38 @@ def _exportable_entries(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
return exportable
+def _is_optional_semantic_sidecar(entry: dict[str, Any]) -> bool:
+ if entry.get("isDir"):
+ return False
+ rel_path = str(entry.get("rel_path") or "")
+ return leaf_name(rel_path) in OPTIONAL_SEMANTIC_SIDECARS
+
+
+async def _filter_existing_optional_sidecars(
+ viking_fs,
+ root_uri: str,
+ entries: list[dict[str, Any]],
+ ctx: RequestContext,
+) -> list[dict[str, Any]]:
+ filtered: list[dict[str, Any]] = []
+ for entry in entries:
+ if not _is_optional_semantic_sidecar(entry):
+ filtered.append(entry)
+ continue
+
+ rel_path = str(entry.get("rel_path") or "")
+ uri = entry.get("uri") or join_uri(root_uri, rel_path)
+ try:
+ exists = await viking_fs.exists(uri, ctx=ctx)
+ except Exception:
+ exists = False
+ if exists:
+ filtered.append(entry)
+ else:
+ logger.info(f"[ovpack] Skipping missing semantic sidecar: {uri}")
+ return filtered
+
+
async def _enqueue_direct_vectorization(
viking_fs,
uri: str,
@@ -475,6 +509,7 @@ async def export_ovpack(
ctx=ctx,
)
)
+ entries = await _filter_existing_optional_sidecars(viking_fs, uri, entries, ctx)
if include_vectors:
ensure_dense_snapshot_supported(vector_store)
report = await check_index_consistency(
@@ -529,6 +564,7 @@ async def backup_ovpack(
to = ensure_ovpack_extension(to)
entries = await _backup_entries(viking_fs, ctx)
+ entries = await _filter_existing_optional_sidecars(viking_fs, "viking://", entries, ctx)
if include_vectors:
ensure_dense_snapshot_supported(vector_store)
report = await check_index_consistency(
diff --git a/tests/misc/test_ovpack_import_policy.py b/tests/misc/test_ovpack_import_policy.py
index e108d94ae..09ec598a7 100644
--- a/tests/misc/test_ovpack_import_policy.py
+++ b/tests/misc/test_ovpack_import_policy.py
@@ -111,6 +111,12 @@ class OverviewOnlyExportVikingFS(FakeExportVikingFS):
}
+class MissingSidecarExportVikingFS(FakeExportVikingFS):
+ def __init__(self) -> None:
+ super().__init__()
+ self.text_files = {}
+
+
class ReservedPathExportVikingFS(FakeExportVikingFS):
def __init__(self) -> None:
super().__init__()
@@ -213,6 +219,33 @@ class FakeBackupVikingFS:
return self.binary_files[uri]
+class MissingSidecarBackupVikingFS(FakeBackupVikingFS):
+ async def tree(
+ self,
+ uri: str,
+ show_all_hidden: bool = False,
+ node_limit=None,
+ level_limit=None,
+ ctx=None,
+ ):
+ if uri == "viking://agent":
+ return [
+ {
+ "rel_path": ".overview.md",
+ "uri": "viking://agent/.overview.md",
+ "isDir": False,
+ "size": 0,
+ }
+ ]
+ return await super().tree(
+ uri,
+ show_all_hidden=show_all_hidden,
+ node_limit=node_limit,
+ level_limit=level_limit,
+ ctx=ctx,
+ )
+
+
class FakeRestoreVectorVikingFS(FakeVikingFS):
async def tree(self, uri: str, node_limit=None, level_limit=None, ctx=None):
self.tree_calls.append(uri)
@@ -520,6 +553,28 @@ async def test_export_ovpack_writes_v2_manifest_with_semantic_sidecars(
assert index_records[0]["text"] == "root abstract"
+async def test_export_ovpack_skips_missing_semantic_sidecars(
+ temp_ovpack_path: Path,
+ request_ctx: RequestContext,
+):
+ await export_ovpack(
+ MissingSidecarExportVikingFS(),
+ "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"))
+
+ manifest_paths = {entry["path"] for entry in manifest["entries"]}
+ assert "demo/files/notes.txt" in names
+ assert "demo/files/.overview.md" not in names
+ assert ".overview.md" not in manifest_paths
+
+
@pytest.mark.asyncio
async def test_backup_restore_contract(temp_ovpack_path: Path, request_ctx: RequestContext):
await backup_ovpack(
@@ -554,6 +609,27 @@ async def test_backup_restore_contract(temp_ovpack_path: Path, request_ctx: Requ
assert fake_fs.tree_calls == ["viking://resources", "viking://user", "viking://agent"]
+async def test_backup_skips_missing_semantic_sidecars(
+ temp_ovpack_path: Path,
+ request_ctx: RequestContext,
+):
+ await backup_ovpack(
+ MissingSidecarBackupVikingFS(),
+ 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"))
+
+ manifest_paths = {entry["path"] for entry in manifest["entries"]}
+ assert "openviking-backup/files/agent/.overview.md" not in names
+ assert "agent/.overview.md" not in manifest_paths
+ assert "agent" in manifest_paths
+
+
@pytest.mark.asyncio
async def test_restore_ovpack_applies_backup_manifest_scalar_metadata(
temp_ovpack_path: Path, request_ctx: RequestContext, monkeypatch: pytest.MonkeyPatch