Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
from __future__ import annotations
from types import SimpleNamespace
from typing import Any
from unittest.mock import AsyncMock
import pytest
from openviking.core.namespace import uri_parts
from openviking.server.identity import RequestContext, Role
from openviking.storage.acl import AclManager
from openviking.storage.collection_schemas import CollectionSchemas
from openviking.storage.expr import And, Contains, Eq, In, Or, PathScope, RawDSL
from openviking.storage.vectordb import engine as vectordb_engine
from openviking.storage.vectordb.collection.collection import Collection
from openviking.storage.vectordb.collection.vikingdb_collection import VikingDBCollection
from openviking.storage.vectordb_adapters.vikingdb_private_adapter import (
VikingDBPrivateCollectionAdapter,
)
from openviking.storage.viking_vector_index_backend import (
VectorTransferRollbackError,
VikingVectorIndexBackend,
_SingleAccountBackend,
)
from openviking_cli.exceptions import InvalidArgumentError
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
class _EnabledAclConfig:
async def get_account(self, account_id: str, field: str):
del account_id, field
return SimpleNamespace(enabled=True)
def _ctx() -> RequestContext:
return RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER)
def _record(record_id: str, uri: str, **overrides: Any) -> dict[str, Any]:
return {
"id": record_id,
"uri": uri,
"level": 2,
"vector": [0.1, 0.2],
"sparse_vector": {"7": 0.8},
"content": f"content:{record_id}",
"created_at": 10,
"updated_at": 11,
"active_count": 3,
"account_id": "acct",
**overrides,
}
class _MemoryTransferBackend(VikingVectorIndexBackend):
"""In-memory I/O boundary for exercising the real transfer methods."""
def __init__(self, records: list[dict[str, Any]]) -> None:
self.records = {str(record["id"]): dict(record) for record in records}
self.upsert_calls = 0
self.fail_upsert_at: int | None = None
self.delete_calls = 0
self.fail_delete_at: int | None = None
self.partial_delete_count = 0
self.drop_delete_requests = False
self.backend_mode = "local"
self.vector_dim = 2
self.scroll_filters = []
self.filter_calls = []
self.acl_manager = None
@property
def mode(self) -> str:
return self.backend_mode
async def _get_backend_for_context(self, ctx):
del ctx
return SimpleNamespace(strict_query=self._query)
async def _query(self, *, filter, limit=10, offset=0, output_fields=None):
del output_fields
self.scroll_filters.append(filter)
return [
dict(record) for record in self.records.values() if _matches_filter(filter, record)
][offset : offset + limit]
async def scroll(
self,
filter=None,
limit: int = 100,
cursor: str | None = None,
output_fields=None,
*,
ctx: RequestContext,
) -> tuple[list[dict[str, Any]], str | None]:
del output_fields, ctx
self.scroll_filters.append(filter)
offset = int(cursor or 0)
ordered = [dict(self.records[key]) for key in sorted(self.records)]
page = ordered[offset : offset + limit]
next_cursor = str(offset + limit) if offset + limit < len(ordered) else None
return page, next_cursor
async def filter(
self,
filter,
limit: int = 10,
offset: int = 0,
output_fields=None,
order_by=None,
order_desc: bool = False,
*,
ctx: RequestContext,
) -> list[dict[str, Any]]:
del output_fields, order_by, order_desc, ctx
self.filter_calls.append((filter, limit, offset))
ordered = [
dict(self.records[key])
for key in sorted(self.records)
if _matches_filter(filter, self.records[key])
]
return ordered[offset : offset + limit]
async def get(self, ids: list[str], *, ctx: RequestContext) -> list[dict[str, Any]]:
del ctx
return [dict(self.records[record_id]) for record_id in ids if record_id in self.records]
async def upsert(self, data: dict[str, Any], *, ctx: RequestContext, options=None) -> str:
del ctx, options
self.upsert_calls += 1
if self.fail_upsert_at == self.upsert_calls:
raise RuntimeError("injected vector write failure")
record = dict(data)
self.records[str(record["id"])] = record
return str(record["id"])
async def upsert_many(
self, data_list: list[dict[str, Any]], *, ctx: RequestContext
) -> list[str]:
return [await self.upsert(data, ctx=ctx) for data in data_list]
async def _upsert_many_raw(
self, data_list: list[dict[str, Any]], *, ctx: RequestContext
) -> list[str]:
return [await self.upsert(data, ctx=ctx) for data in data_list]
async def delete(self, ids: list[str], *, ctx: RequestContext) -> int:
del ctx
self.delete_calls += 1
if self.drop_delete_requests:
return 0
deleted = 0
for record_id in ids:
if self.records.pop(record_id, None) is not None:
deleted += 1
if self.fail_delete_at == self.delete_calls and deleted >= self.partial_delete_count:
self.fail_delete_at = None
raise RuntimeError("injected vector delete failure")
return deleted
async def _strict_transfer_count(self, ctx, filter):
del ctx, filter
return len(self.records)
async def _strict_transfer_page(self, ctx, filter, *, limit, cursor, output_fields):
return await self.scroll(
filter=filter,
limit=limit,
cursor=cursor,
output_fields=output_fields,
ctx=ctx,
)
async def _strict_transfer_get(self, ctx, ids):
return await self.get(ids, ctx=ctx)
async def _strict_transfer_delete(self, ctx, ids):
return await self.delete(ids, ctx=ctx)
def _matches_filter(expr, record: dict[str, Any]) -> bool:
if expr is None:
return True
if isinstance(expr, And):
return all(_matches_filter(cond, record) for cond in expr.conds)
if isinstance(expr, Or):
return any(_matches_filter(cond, record) for cond in expr.conds)
if isinstance(expr, Eq):
return record.get(expr.field) == expr.value
if isinstance(expr, In):
value = record.get(expr.field)
if isinstance(value, list):
return any(item in expr.values for item in value)
return value in expr.values
if isinstance(expr, Contains):
return expr.substring in str(record.get(expr.field, ""))
if isinstance(expr, PathScope):
root = uri_parts(expr.path)
path = uri_parts(str(record.get(expr.field, "")))
if path[: len(root)] != root:
return False
return expr.depth == -1 or len(path) - len(root) <= expr.depth
if isinstance(expr, RawDSL) and expr.payload["op"] in {"must", "must_not"}:
matched = _matches_filter(In(expr.payload["field"], expr.payload["conds"]), record)
return matched if expr.payload["op"] == "must" else not matched
if isinstance(expr, RawDSL) and expr.payload["op"] == "prefix":
return str(record.get(expr.payload["field"], "")).startswith(expr.payload["prefix"])
raise AssertionError(f"Unexpected filter expression in test: {expr!r}")
class _RealAclMemoryTransferBackend(_MemoryTransferBackend):
"""Memory vector boundary with the production ACL manager."""
def __init__(self, records: list[dict[str, Any]]) -> None:
super().__init__(records)
self.acl_manager = AclManager(self, _EnabledAclConfig())
self.scroll_output_fields = []
async def scroll(
self,
filter=None,
limit: int = 100,
cursor: str | None = None,
output_fields=None,
*,
ctx: RequestContext,
) -> tuple[list[dict[str, Any]], str | None]:
del ctx
self.scroll_output_fields.append(list(output_fields or []))
self.scroll_filters.append(filter)
offset = int(cursor or 0)
ordered = [
dict(self.records[key])
for key in sorted(self.records)
if _matches_filter(filter, self.records[key])
]
page = ordered[offset : offset + limit]
next_cursor = str(offset + limit) if offset + limit < len(ordered) else None
return page, next_cursor
async def _strict_transfer_count(self, ctx, filter):
del ctx
return sum(_matches_filter(filter, record) for record in self.records.values())
async def upsert_many(
self, data_list: list[dict[str, Any]], *, ctx: RequestContext
) -> list[str]:
return await VikingVectorIndexBackend.upsert_many(self, data_list, ctx=ctx)
def _records_under(
backend: _MemoryTransferBackend, uri: str, *, recursive: bool = True
) -> list[dict[str, Any]]:
return [
record
for record in backend.records.values()
if record["uri"] == uri
or record["uri"].startswith(uri + "#")
or (recursive and record["uri"].startswith(uri + "/"))
]
@pytest.mark.asyncio
async def test_copy_uri_mapping_scans_real_local_path_records(vector_backend_factory, tmp_path):
if not getattr(vectordb_engine, "PersistStore", None):
pytest.skip("local persistent vectordb engine is not available in this environment")
source = "viking://resources/src.md"
target = "viking://resources/dst.md"
backend = vector_backend_factory(
config=VectorDBBackendConfig(
backend="local",
name="context",
dimension=4,
path=str(tmp_path),
)
)
try:
assert await backend.create_collection(
"context", CollectionSchemas.context_collection("context", 4)
)
assert (
await backend.upsert(
_record(
"source-file",
source,
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:00Z",
updated_at="2026-08-20T00:00:00Z",
),
ctx=_ctx(),
)
== "source-file"
)
result = await backend.copy_uri_mapping(_ctx(), source, target, recursive=False)
assert result.scanned == 1
copied = await backend.get_context_by_uri(target, ctx=_ctx())
assert [record["uri"] for record in copied] == [target]
first_page, cursor = await backend.scroll(limit=1, ctx=_ctx())
assert cursor is not None
last_page, cursor = await backend.scroll(limit=2, cursor=cursor, ctx=_ctx())
assert cursor is None
assert [record["uri"] for record in first_page + last_page] == [source, target]
finally:
await backend.close()
@pytest.mark.asyncio
async def test_copy_uri_mapping_keeps_source_and_copies_all_pages():
source = "viking://resources/src"
records = [_record("source-root", source)] + [
_record(f"source-{index:03d}", f"{source}/file-{index:03d}.md") for index in range(204)
]
backend = _MemoryTransferBackend(records)
result = await backend.copy_uri_mapping(
_ctx(), source, "viking://resources/dst", recursive=True
)
assert result.scanned == 205
assert result.written == 205
assert result.batches == 3
assert len(_records_under(backend, source)) == 205
assert len(_records_under(backend, "viking://resources/dst")) == 205
@pytest.mark.asyncio
async def test_get_l2_abstracts_by_uris_uses_strict_batched_lookup():
backend = _MemoryTransferBackend([])
backend._strict_transfer_page = AsyncMock(
side_effect=[
(
[
{
"uri": "viking://resources/a.md",
"abstract": "summary-a",
"updated_at": 1,
},
{
"uri": "viking://resources/b.md",
"abstract": "",
"updated_at": 1,
},
],
None,
)
]
)
result = await backend.get_l2_abstracts_by_uris(
["viking://resources/a.md", "viking://resources/b.md"],
ctx=_ctx(),
)
assert result == {"viking://resources/a.md": "summary-a"}
call = backend._strict_transfer_page.await_args
assert call.kwargs["output_fields"] == ["uri", "abstract", "updated_at"]
assert call.args[1] == And(
[
In("uri", ["viking://resources/a.md", "viking://resources/b.md"]),
Eq("level", 2),
]
)
@pytest.mark.asyncio
async def test_scroll_propagates_real_adapter_query_failure():
backend = _SingleAccountBackend(
VectorDBBackendConfig(),
bound_account_id="acct",
shared_adapter=SimpleNamespace(mode="local"),
)
backend._async_adapter = SimpleNamespace(
call=AsyncMock(side_effect=RuntimeError("injected query failure"))
)
with pytest.raises(RuntimeError, match="injected query failure"):
await backend.scroll(limit=100, output_fields=["id", "uri"])
@pytest.mark.asyncio
async def test_strict_delete_removes_existing_subset_when_attempted_ids_include_missing():
adapter_call = AsyncMock(
side_effect=[
[{"id": "written", "account_id": "acct"}],
1,
]
)
backend = _SingleAccountBackend(
VectorDBBackendConfig(),
bound_account_id="acct",
shared_adapter=SimpleNamespace(mode="local"),
)
backend._async_adapter = SimpleNamespace(call=adapter_call)
deleted = await backend.strict_delete(["written", "never-written"])
assert deleted == 1
assert adapter_call.await_args_list[1].args == ("delete",)
assert adapter_call.await_args_list[1].kwargs == {"ids": ["written"]}
@pytest.mark.asyncio
async def test_transfer_scan_fails_closed_on_repeated_record_page():
backend = _MemoryTransferBackend(
[
_record("source-a", "viking://resources/src/a.md"),
_record("source-b", "viking://resources/src/b.md"),
]
)
async def repeated_page(*_args, **_kwargs):
record = dict(backend.records["source-a"])
return [record], "1"
backend._strict_transfer_page = repeated_page
with pytest.raises(RuntimeError, match="duplicate vector record"):
await backend.copy_uri_mapping(
_ctx(), "viking://resources/src", "viking://resources/dst", recursive=True
)
@pytest.mark.asyncio
async def test_copy_uri_mapping_preserves_dense_and_sparse_payloads():
source = "viking://resources/src.md"
backend = _MemoryTransferBackend(
[
_record("source-file", source, sparse_vector={}),
_record("source-l0", source, level=0, vector=[]),
_record("outside", "viking://resources/other.md"),
]
)
result = await backend.copy_uri_mapping(
_ctx(), source, "viking://resources/dst.md", recursive=False
)
copied = _records_under(backend, "viking://resources/dst.md")
assert result.written == 2
assert {record["uri"] for record in copied} == {
"viking://resources/dst.md",
}
assert {tuple(record["vector"]) for record in copied} == {(), (0.1, 0.2)}
assert {tuple(record["sparse_vector"].items()) for record in copied} == {
(),
(("7", 0.8),),
}
@pytest.mark.asyncio
@pytest.mark.parametrize("mode", ["local", "volcengine", "vikingdb", "bytedviking", "custom"])
async def test_remote_transfer_scope_avoids_unsupported_contains_filter(mode):
source = "viking://resources/src.md"
backend = _MemoryTransferBackend([_record("source", source)])
backend.backend_mode = mode
await backend.copy_uri_mapping(_ctx(), source, "viking://resources/dst.md", recursive=False)
assert backend.scroll_filters
for filter_expr in backend.scroll_filters:
assert isinstance(filter_expr, And)
scopes = next(cond for cond in filter_expr.conds if isinstance(cond, Or)).conds
assert all(isinstance(scope, Eq) and scope.field == "uri" for scope in scopes)
@pytest.mark.asyncio
@pytest.mark.parametrize("selected_entries", [False, True], ids=["source", "target"])
@pytest.mark.parametrize("recursive", [False, True], ids=["file", "directory"])
@pytest.mark.parametrize("mode", ["vikingdb", "bytedviking", "custom"])
async def test_transfer_scan_emits_supported_aggregate_request(
monkeypatch, selected_entries, recursive, mode
):
root = "viking://resources/docs"
entry = f"{root}/file.md"
uri = root if recursive else entry
records = [
_record("file", entry),
_record("chunk", entry + "#chunk_0001"),
_record("sibling", "viking://resources/other.md"),
]
backend = _RealAclMemoryTransferBackend(records)
backend.backend_mode = mode
adapter = VikingDBPrivateCollectionAdapter(
host="unused.invalid",
headers=None,
project_name="test",
collection_name="context",
index_name="default",
)
collection = VikingDBCollection(
host="unused.invalid",
meta_data={"ProjectName": "test", "CollectionName": "context"},
)
adapter._collection = Collection(collection)
requests = []
def validate_dsl(node):
# The deployed recall service accepts path-index must queries, not
# contains/prefix. Validate the actual adapter output at the I/O boundary.
assert node["op"] in {"and", "or", "must"}, node
if node["op"] in {"and", "or"}:
for child in node["conds"]:
validate_dsl(child)
elif node["field"] == "uri":
assert all(value.startswith("/") for value in node["conds"])
assert node["para"] in {"-d=0", "-d=-1"}
async def count(ctx, filter):
def data_post(path, data):
assert path == "/api/vikingdb/data/agg"
assert data["project"] == "test"
assert data["collection_name"] == "context"
assert data["index_name"] == "default"
assert data["op"] == "count"
validate_dsl(data["filter"])
requests.append(data)
return {"agg": {"_total": sum(_matches_filter(filter, record) for record in records)}}
monkeypatch.setattr(collection, "_data_post", data_post)
return adapter.count(filter)
monkeypatch.setattr(backend, "_strict_transfer_count", count)
found, _ = await backend._scan_uri_transfer_scope(
_ctx(),
uri,
recursive=recursive,
include_full_records=True,
entry_uris=[entry] if selected_entries else None,
)
assert requests
assert {record["id"] for record in found} == (
{"file", "chunk"} if recursive and not selected_entries else {"file"}
)
@pytest.mark.asyncio
async def test_legacy_transfer_reads_use_private_adapter_query_and_fetch(monkeypatch):
source = "viking://resources/source.md"
backend = _MemoryTransferBackend([])
adapter = VikingDBPrivateCollectionAdapter(
host="unused.invalid",
headers=None,
project_name="test",
collection_name="context",
index_name="default",
)
collection = VikingDBCollection(
host="unused.invalid", meta_data={"ProjectName": "test", "CollectionName": "context"}
)
adapter._collection = Collection(collection)
account_backend = _SingleAccountBackend(VectorDBBackendConfig(), "acct", shared_adapter=adapter)
monkeypatch.setattr(
backend, "_get_backend_for_context", AsyncMock(return_value=account_backend)
)
monkeypatch.setattr(
backend,
"_strict_transfer_get",
VikingVectorIndexBackend._strict_transfer_get.__get__(backend),
)
adapter._dimension = 2
paths = []
def data_post(path, data):
paths.append(path)
if path == "/api/vikingdb/data/search/vector":
assert data["limit"] == 100 and data["offset"] == 0
assert len(data["dense_vector"]) == 2
assert "field" not in data and "order" not in data
assert data["filter"] == {
"op": "and",
"conds": [
{"op": "must", "field": "account_id", "conds": ["acct"]},
{
"op": "and",
"conds": [
{"op": "must", "field": "account_id", "conds": ["acct"]},
{
"op": "must",
"field": "uri",
"conds": ["/resources/source.md"],
"para": "-d=0",
},
],
},
],
}
return {
"data": [
{"id": "file", "fields": {"uri": "/resources/source.md"}},
{"id": "gone", "fields": {"uri": "/resources/source.md"}},
]
}
if path == "/api/vikingdb/data/fetch_in_collection":
assert data["ids"] == ["file", "gone"]
return {
"fetch": [
{
"id": "file",
"fields": {
"uri": "/resources/source.md",
"account_id": "acct",
"vector": [0.1, 0.2],
},
}
],
"ids_not_exist": ["gone"],
}
raise AssertionError(f"Legacy reads must not use aggregate or scalar search: {path}")
monkeypatch.setattr(collection, "_data_post", data_post)
records, _ = await backend._read_uri_transfer_entries(
_ctx(), [source], include_full_records=True
)
assert [(r["id"], r["uri"], r["vector"]) for r in records] == [("file", source, [0.1, 0.2])]
assert paths == ["/api/vikingdb/data/search/vector", "/api/vikingdb/data/fetch_in_collection"]
@pytest.mark.asyncio
async def test_l2_diff_scan_reads_every_page_under_target_directory():
root = "viking://resources/docs"
backend = _RealAclMemoryTransferBackend(
[
_record("a", f"{root}/a.py", md5="ma", abstract="A"),
_record("b", f"{root}/sub/b.py", md5="mb", abstract="B"),
_record("ghost", f"{root}/ghost.py", md5="mg", abstract="G"),
_record("directory", root, level=1),
_record("outside", "viking://resources/other.py"),
_record("other-account", f"{root}/private.py", account_id="other"),
]
)
records = await backend.get_l2_diff_records_under_uri(root, ctx=_ctx(), batch_size=2)
assert records == {
f"{root}/a.py": {"md5": "ma", "abstract": "A"},
f"{root}/ghost.py": {"md5": "mg", "abstract": "G"},
f"{root}/sub/b.py": {"md5": "mb", "abstract": "B"},
}
assert len(backend.scroll_filters) == 2
@pytest.mark.asyncio
async def test_incremental_inventory_reads_all_semantic_levels_under_target():
root = "viking://resources/docs"
files = [_record(f"file-{i}", f"{root}/{i}.md", md5=f"md5-{i}") for i in range(5998)]
backend = _RealAclMemoryTransferBackend(
[
_record("root-l0", root, level=0),
_record("root-l1", root, level=1),
*files,
_record("outside", "viking://resources/other.py"),
_record("other-account", f"{root}/private.py", account_id="other"),
]
)
original_page = backend._strict_transfer_page
original_filter = backend.filter
async def bounded_filter(*args, limit=10, **kwargs):
assert limit <= 5000, "VikingDB rejects oversized queries"
return await original_filter(*args, limit=limit, **kwargs)
async def bounded_page(ctx, filter, *, limit, cursor, output_fields):
assert limit <= 5000, "VikingDB rejects oversized pages"
return await original_page(
ctx, filter, limit=limit, cursor=cursor, output_fields=output_fields
)
backend.filter = bounded_filter
backend._strict_transfer_page = bounded_page
incremental = await backend.get_incremental_inventory_under_uri(root, ctx=_ctx())
reindex = await backend.get_reindex_inventory_under_uri(root, ctx=_ctx())
assert reindex == incremental
assert len(reindex) == 6000
assert reindex["root-l0"]["level"] == 0
assert reindex["root-l1"]["level"] == 1
assert reindex["file-5997"]["md5"] == "md5-5997"
assert "outside" not in reindex and "other-account" not in reindex
backend._strict_transfer_count = AsyncMock(return_value=6001)
with pytest.raises(RuntimeError, match="ended after 6000 of 6001"):
await backend.get_reindex_inventory_under_uri(root, ctx=_ctx())
@pytest.mark.asyncio
async def test_incremental_inventory_projects_request_scalar_fields():
uri = "viking://user/alice/memories/events/a.md"
backend = _RealAclMemoryTransferBackend(
[
_record("base", uri, md5="ma", search_tags=["env=test"]),
_record("chunk", uri + "#chunk_0000", search_tags=["env=test"]),
_record("sibling", uri + "-other.md"),
_record("literal", uri + "#chunk_notes"),
]
)
incremental = await backend.get_incremental_inventory_under_uri(
uri,
ctx=_ctx(),
recursive=False,
output_fields=["search_tags"],
)
reindex = await backend.get_reindex_inventory_under_uri(
uri,
ctx=_ctx(),
recursive=False,
include_virtual_chunks=True,
output_fields=["search_tags"],
)
assert set(incremental) == {"base"}
assert set(reindex) == {"base", "chunk"}
assert reindex["base"] == incremental["base"]
assert reindex["chunk"]["search_tags"] == ["env=test"]
assert all("search_tags" in fields for fields in backend.scroll_output_fields)
assert all(
not {"vector", "sparse_vector", "content"}.intersection(fields)
for fields in backend.scroll_output_fields
)
@pytest.mark.asyncio
async def test_incremental_inventory_by_uris_reads_exact_uri_groups_only():
first = "viking://resources/docs/a.py"
second = "viking://resources/docs/b.py"
backend = _RealAclMemoryTransferBackend(
[
_record("a-l2", first, level=2, md5="ma", abstract="A"),
_record("b-l2", second, level=2, md5="mb", abstract="B"),
_record("parent-l1", "viking://resources/docs", level=1),
_record("sibling-l2", "viking://resources/docs/c.py", level=2),
]
)
records = await backend.get_incremental_inventory_by_uris(
[first, second],
ctx=_ctx(),
batch_size=1,
output_fields=["id", "uri", "level", "md5", "abstract"],
)
assert records == {
first: {
"a-l2": {
"id": "a-l2",
"uri": first,
"level": 2,
"md5": "ma",
"abstract": "A",
}
},
second: {
"b-l2": {
"id": "b-l2",
"uri": second,
"level": 2,
"md5": "mb",
"abstract": "B",
}
},
}
assert all(isinstance(filter, And) for filter in backend.scroll_filters)
assert all(
any(isinstance(condition, In) and condition.field == "uri" for condition in filter.conds)
for filter in backend.scroll_filters
)
@pytest.mark.asyncio
async def test_incremental_inventory_by_uris_uses_one_exact_filter_per_uri_chunk():
first = "viking://resources/docs/a.py"
second = "viking://resources/docs/b.py"
backend = _RealAclMemoryTransferBackend(
[
_record("a-l2", first, level=2, md5="ma"),
_record("b-l2", second, level=2, md5="mb"),
]
)
records = await backend.get_incremental_inventory_by_uris(
[first, second],
ctx=_ctx(),
batch_size=2,
)
assert set(records) == {first, second}
assert len(backend.filter_calls) == 1
assert backend.scroll_filters == []
scope, limit, offset = backend.filter_calls[0]
assert offset == 0
assert limit == 7 # 3 canonical levels per URI plus the truncation sentinel.
assert isinstance(scope, And)
assert any(
isinstance(condition, In)
and condition.field == "uri"
and set(condition.values) == {first, second}
for condition in scope.conds
)
@pytest.mark.asyncio
async def test_incremental_hydration_fetches_records_by_primary_key():
root = "viking://resources/docs"
first = _record("root-l0", root, level=0, abstract="root abstract")
second = _record("file-l2", f"{root}/a.py", level=2, md5="ma")
backend = _MemoryTransferBackend([first, second])
backend._strict_transfer_page = AsyncMock(
side_effect=AssertionError("hydration must not filter on the primary key")
)
backend._strict_transfer_get = AsyncMock(return_value=[dict(first), dict(second)])
records = await backend.hydrate_incremental_records(
{
"root-l0": {"uri": root, "level": 0},
"file-l2": {"uri": f"{root}/a.py", "level": 2},
},
ctx=_ctx(),
)
assert set(records) == {"root-l0", "file-l2"}
assert records["root-l0"]["abstract"] == "root abstract"
assert records["file-l2"]["md5"] == "ma"
# Point-get is used, never an In("id", ...) scalar filter.
backend._strict_transfer_page.assert_not_awaited()
backend._strict_transfer_get.assert_awaited_once_with(_ctx(), ["root-l0", "file-l2"])
# Vector payloads returned by the fetch are dropped by client-side projection.
for hydrated in records.values():
assert "vector" not in hydrated
assert "sparse_vector" not in hydrated
assert "content" not in hydrated
@pytest.mark.asyncio
async def test_incremental_hydration_propagates_fetch_failure():
backend = _MemoryTransferBackend([])
backend._strict_transfer_get = AsyncMock(side_effect=RuntimeError("fetch failed"))
with pytest.raises(RuntimeError, match="fetch failed"):
await backend.hydrate_incremental_records(
{"file-l2": {"uri": "viking://resources/docs/a.py", "level": 2}},
ctx=_ctx(),
)
@pytest.mark.asyncio
async def test_incremental_hydration_rejects_mismatched_record_identity():
root = "viking://resources/docs"
backend = _MemoryTransferBackend([])
backend._strict_transfer_get = AsyncMock(
return_value=[_record("file-l2", f"{root}/wrong.py", level=2)]
)
with pytest.raises(RuntimeError, match="identity mismatch"):
await backend.hydrate_incremental_records(
{"file-l2": {"uri": f"{root}/a.py", "level": 2}},
ctx=_ctx(),
)
@pytest.mark.asyncio
async def test_incremental_hydration_returns_only_records_still_present():
backend = _MemoryTransferBackend([])
backend._strict_transfer_get = AsyncMock(return_value=[])
records = await backend.hydrate_incremental_records(
{"gone": {"uri": "viking://resources/docs/a.py", "level": 2}},
ctx=_ctx(),
)
assert records == {}
@pytest.mark.asyncio
async def test_incremental_hydration_projects_dynamic_non_vector_schema_fields():
root = "viking://resources/docs"
record = _record(
"file-l2",
f"{root}/a.py",
level=2,
business_priority=7,
)
backend = _MemoryTransferBackend([record])
backend.get_collection_meta = AsyncMock(
return_value={
"Fields": [
{"FieldName": "id"},
{"FieldName": "uri"},
{"FieldName": "level"},
{"FieldName": "abstract"},
{"FieldName": "business_priority"},
{"FieldName": "vector"},
{"FieldName": "sparse_vector"},
{"FieldName": "content"},
]
}
)
hydrated = await backend.hydrate_incremental_records(
{"file-l2": {"uri": f"{root}/a.py", "level": 2}},
ctx=_ctx(),
)
# Dynamic non-vector schema fields survive; vector payloads are dropped.
assert hydrated["file-l2"]["business_priority"] == 7
assert "vector" not in hydrated["file-l2"]
assert "sparse_vector" not in hydrated["file-l2"]
assert "content" not in hydrated["file-l2"]
@pytest.mark.asyncio
async def test_incremental_hydration_honors_explicit_summary_projection():
root = "viking://resources/docs"
record = _record(
"file-l2",
f"{root}/a.py",
level=2,
abstract="summary",
business_priority=7,
)
backend = _MemoryTransferBackend([record])
backend.get_collection_meta = AsyncMock(
side_effect=AssertionError("explicit projection must not read collection meta")
)
hydrated = await backend.hydrate_incremental_records(
{"file-l2": {"uri": f"{root}/a.py", "level": 2}},
ctx=_ctx(),
output_fields={"abstract"},
)
# Explicit projection keeps only id/uri/level plus the requested field, even
# though the point-get returns every stored column.
assert hydrated["file-l2"] == {
"id": "file-l2",
"uri": f"{root}/a.py",
"level": 2,
"abstract": "summary",
}
@pytest.mark.asyncio
async def test_l2_diff_scan_reads_real_local_backend(vector_backend_factory, tmp_path):
if not getattr(vectordb_engine, "PersistStore", None):
pytest.skip("local persistent vectordb engine is not available in this environment")
root = "viking://resources/docs"
backend = vector_backend_factory(
config=VectorDBBackendConfig(
backend="local", name="context", dimension=4, path=str(tmp_path)
)
)
try:
assert await backend.create_collection(
"context", CollectionSchemas.context_collection("context", 4)
)
records = [
_record(
"a",
f"{root}/a.py",
md5="ma",
abstract="A",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:00Z",
updated_at="2026-08-20T00:00:00Z",
),
_record(
"ghost",
f"{root}/ghost.py",
md5="mg",
abstract="G",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:01Z",
updated_at="2026-08-20T00:00:01Z",
),
_record(
"outside",
"viking://resources/other.py",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:02Z",
updated_at="2026-08-20T00:00:02Z",
),
]
await backend.upsert_many(records, ctx=_ctx())
result = await backend.get_l2_diff_records_under_uri(root, ctx=_ctx(), batch_size=1)
assert result == {
f"{root}/a.py": {"md5": "ma", "abstract": "A"},
f"{root}/ghost.py": {"md5": "mg", "abstract": "G"},
}
finally:
await backend.close()
@pytest.mark.asyncio
async def test_incremental_inventory_and_hydration_read_real_local_backend(
vector_backend_factory, tmp_path
):
if not getattr(vectordb_engine, "PersistStore", None):
pytest.skip("local persistent vectordb engine is not available in this environment")
root = "viking://resources/docs"
backend = vector_backend_factory(
config=VectorDBBackendConfig(
backend="local", name="context", dimension=4, path=str(tmp_path)
)
)
try:
assert await backend.create_collection(
"context", CollectionSchemas.context_collection("context", 4)
)
await backend.upsert_many(
[
_record(
"root-l0",
root,
level=0,
abstract="root abstract",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:00Z",
updated_at="2026-08-20T00:00:00Z",
),
_record(
"root-l1",
root,
level=1,
abstract="root overview",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:01Z",
updated_at="2026-08-20T00:00:01Z",
),
_record(
"a-l2",
f"{root}/a.py",
md5="ma",
abstract="A",
vector=[0.1, 0.2, 0.3, 0.4],
created_at="2026-08-20T00:00:02Z",
updated_at="2026-08-20T00:00:02Z",
),
],
ctx=_ctx(),
)
inventory = await backend.get_incremental_inventory_under_uri(
root, ctx=_ctx(), batch_size=1
)
hydrated = await backend.hydrate_incremental_records(inventory, ctx=_ctx())
assert set(inventory) == {"root-l0", "root-l1", "a-l2"}
assert inventory["a-l2"]["md5"] == "ma"
assert hydrated["root-l0"]["abstract"] == "root abstract"
assert hydrated["a-l2"]["abstract"] == "A"
assert "vector" not in hydrated["a-l2"]
assert "sparse_vector" not in hydrated["a-l2"]
finally:
await backend.close()
@pytest.mark.asyncio
async def test_l2_diff_scan_fails_closed_on_repeated_cursor(monkeypatch):
backend = _MemoryTransferBackend([])
monkeypatch.setattr(backend, "_strict_transfer_count", AsyncMock(return_value=3))
page = [{"uri": "viking://resources/docs/a.py", "md5": "m"}]
monkeypatch.setattr(
backend,
"_strict_transfer_page",
AsyncMock(side_effect=[(page, "same"), (page, "same")]),
)
with pytest.raises(RuntimeError, match="duplicate L2 URI|cursor repeated"):
await backend.get_l2_diff_records_under_uri(
"viking://resources/docs", ctx=_ctx(), batch_size=1
)
@pytest.mark.asyncio
async def test_l2_diff_scan_does_not_ignore_trailing_page_after_count(monkeypatch):
backend = _MemoryTransferBackend([])
monkeypatch.setattr(backend, "_strict_transfer_count", AsyncMock(return_value=1))
monkeypatch.setattr(
backend,
"_strict_transfer_page",
AsyncMock(
side_effect=[
([{"uri": "viking://resources/docs/a.py"}], "1"),
([{"uri": "viking://resources/docs/new.py"}], None),
]
),
)
with pytest.raises(RuntimeError, match="count was 1"):
await backend.get_l2_diff_records_under_uri(
"viking://resources/docs", ctx=_ctx(), batch_size=1
)
@pytest.mark.asyncio
async def test_incremental_inventory_retries_a_transiently_short_cursor(monkeypatch):
backend = _MemoryTransferBackend([])
root = "viking://resources/docs"
monkeypatch.setattr(backend, "_strict_transfer_count", AsyncMock(return_value=2))
first = {"id": "root-l0", "uri": root, "level": 0, "md5": ""}
second = {"id": "root-l1", "uri": root, "level": 1, "md5": ""}
monkeypatch.setattr(
backend,
"_strict_transfer_page",
AsyncMock(
side_effect=[
([first], None),
([first, second], None),
]
),
)
records = await backend.get_incremental_inventory_under_uri(root, ctx=_ctx(), batch_size=2)
assert set(records) == {"root-l0", "root-l1"}
assert backend._strict_transfer_count.await_count == 2
@pytest.mark.asyncio
async def test_incremental_inventory_retries_a_transient_count_undershoot(monkeypatch):
backend = _MemoryTransferBackend([])
root = "viking://resources/docs"
monkeypatch.setattr(
backend,
"_strict_transfer_count",
AsyncMock(side_effect=[1, 2]),
)
first = {"id": "root-l0", "uri": root, "level": 0, "md5": ""}
second = {"id": "root-l1", "uri": root, "level": 1, "md5": ""}
monkeypatch.setattr(
backend,
"_strict_transfer_page",
AsyncMock(
side_effect=[
([first, second], None),
([first, second], None),
]
),
)
records = await backend.get_incremental_inventory_under_uri(root, ctx=_ctx(), batch_size=2)
assert set(records) == {"root-l0", "root-l1"}
assert backend._strict_transfer_count.await_count == 2
@pytest.mark.asyncio
@pytest.mark.parametrize(
"bad_record",
[
{"md5": "missing-uri"},
{"uri": "viking://resources/other.py", "md5": "outside"},
],
)
async def test_l2_diff_scan_fails_closed_on_invalid_scoped_record(monkeypatch, bad_record):
backend = _MemoryTransferBackend([])
monkeypatch.setattr(backend, "_strict_transfer_count", AsyncMock(return_value=1))
monkeypatch.setattr(
backend,
"_strict_transfer_page",
AsyncMock(return_value=([bad_record], None)),
)
with pytest.raises(RuntimeError, match="invalid L2 URI"):
await backend.get_l2_diff_records_under_uri("viking://resources/docs", ctx=_ctx())
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_overwrites_exact_target_and_leaves_independent_chunks(
transfer_method,
):
source = "viking://resources/src.md"
target = "viking://resources/dst.md"
backend = _MemoryTransferBackend(
[
_record("source-file", source, content="new-file"),
_record("source-chunk", f"{source}#chunk_0001", content="new-chunk"),
_record("old-target-file", target, content="old-file"),
_record("old-target-chunk", f"{target}#chunk_0001", content="old-chunk"),
_record("obsolete-target-chunk", f"{target}#chunk_0002", content="obsolete"),
]
)
result = await getattr(backend, transfer_method)(_ctx(), source, target, recursive=False)
targets = sorted(_records_under(backend, target), key=lambda record: record["uri"])
assert result.scanned == result.written == 1
assert [(record["uri"], record["content"]) for record in targets] == [
(target, "new-file"),
(f"{target}#chunk_0001", "old-chunk"),
(f"{target}#chunk_0002", "obsolete"),
]
assert backend.records["source-chunk"]["content"] == "new-chunk"
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_preserves_target_records_for_unaffected_entries(transfer_method):
source = "viking://resources/src"
target = "viking://resources/dst"
unique_target = f"{target}/unique.md"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md", content="new-a"),
_record("old-target-root", target),
_record("old-target-a", f"{target}/a.md", content="old-a"),
_record("unique-target", unique_target, content="keep-me"),
]
)
await getattr(backend, transfer_method)(_ctx(), source, target, recursive=True)
target_records = _records_under(backend, target)
assert (
next(record for record in target_records if record["uri"] == unique_target)["content"]
== "keep-me"
)
assert (
next(record for record in target_records if record["uri"] == f"{target}/a.md")["content"]
== "new-a"
)
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
@pytest.mark.parametrize("backend_mode", ["local", "volcengine", "vikingdb"])
async def test_merge_target_scan_excludes_unrelated_subtrees(
transfer_method, backend_mode, monkeypatch
):
source, target = "viking://resources/source", "viking://resources/target"
affected = f"{target}/a.md"
source_records = [_record("source-root", source), _record("source-file", f"{source}/a.md")]
old_records = [_record("old-root", target), _record("old-file", affected)]
unique_records = [_record(f"old-chunk-{i}", f"{affected}#chunk_{i}") for i in range(205)] + [
_record(f"unique-{i}", f"{target}/unrelated/file-{i}.md") for i in range(1000)
]
backend = _RealAclMemoryTransferBackend(source_records + old_records + unique_records)
backend.acl_manager = None
backend.backend_mode = backend_mode
original_query = backend._query
read_ids: list[str] = []
async def counted_query(*args, **kwargs):
page = await original_query(*args, **kwargs)
read_ids.extend(str(record["id"]) for record in page)
return page
monkeypatch.setattr(backend, "_query", counted_query)
result = await getattr(backend, transfer_method)(
_ctx(), source, target, recursive=True, source_uris=[source, f"{source}/a.md"]
)
assert not set(read_ids).intersection(record["id"] for record in unique_records)
assert {record["id"] for record in old_records}.issubset(read_ids)
assert result.written == 2
assert not set(backend.records).intersection(record["id"] for record in old_records)
assert all(backend.records[record["id"]] == record for record in unique_records)
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_direct_recursive_transfer_keeps_complete_target_scan(transfer_method):
source, target = "viking://resources/source", "viking://resources/target"
old_ids = [f"old-{i}" for i in range(101)]
backend = _RealAclMemoryTransferBackend(
[_record("source", source)] + [_record(record_id, target) for record_id in old_ids]
)
backend.acl_manager = None
await getattr(backend, transfer_method)(_ctx(), source, target, recursive=True)
assert not set(old_ids).intersection(backend.records)
assert len(_records_under(backend, target)) == 1
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_target_replacement_cleans_exact_entries_across_batches(transfer_method):
source, target = "viking://resources/source", "viking://resources/target"
source_records = [_record(f"source-{i}", f"{source}/file-{i}.md") for i in range(101)]
old_records = [_record(f"old-{i}", f"{target}/file-{i}.md") for i in range(101)]
backend = _RealAclMemoryTransferBackend(source_records + old_records)
backend.acl_manager = None
result = await getattr(backend, transfer_method)(_ctx(), source, target, recursive=True)
assert result.written == 101
assert len(_records_under(backend, target)) == 101
assert not set(backend.records).intersection(record["id"] for record in old_records)
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_empty_source_file_preserves_old_target_vectors(transfer_method):
source = "viking://resources/src.md"
target = "viking://resources/dst.md"
backend = _MemoryTransferBackend(
[
_record("old-target-file", target),
_record("old-target-chunk", f"{target}#chunk_0001"),
_record("outside", "viking://resources/outside.md"),
]
)
original_records = dict(backend.records)
result = await getattr(backend, transfer_method)(_ctx(), source, target, recursive=False)
assert result.scanned == 0
assert result.written == 0
assert result.deleted == 0
assert backend.records == original_records
assert backend.delete_calls == backend.upsert_calls == 0
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_write_failure_keeps_source_without_restoring_old_target(
transfer_method,
):
source = "viking://resources/src.md"
target = "viking://resources/dst.md"
backend = _MemoryTransferBackend(
[
_record("source-file", source),
_record("source-l0", source, level=0),
_record("old-target-file", target, content="do-not-restore"),
_record("old-target-l0", target, level=0, content="do-not-restore"),
]
)
backend.fail_upsert_at = 2
with pytest.raises(RuntimeError, match="injected vector write failure"):
await getattr(backend, transfer_method)(_ctx(), source, target, recursive=False)
assert len(_records_under(backend, source, recursive=False)) == 2
assert _records_under(backend, target, recursive=False) == []
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_source_uris_limits_source_and_target_replacement_scope(
transfer_method,
):
source = "viking://resources/src"
target = "viking://resources/dst"
source_b = f"{source}/b.md"
target_b = f"{target}/b.md"
backend = _MemoryTransferBackend(
[
_record("source-root", source, content="new-root"),
_record("source-a", f"{source}/a.md", content="new-a"),
_record("source-b", source_b, content="source-b-stays"),
_record("old-target-root", target, content="old-root"),
_record("old-target-a", f"{target}/a.md", content="old-a"),
_record("old-target-b", target_b, content="target-b-stays"),
]
)
result = await getattr(backend, transfer_method)(
_ctx(),
source,
target,
recursive=True,
source_uris=[source, f"{source}/a.md"],
)
assert result.scanned == 2
assert (
next(record for record in backend.records.values() if record["uri"] == target_b)["content"]
== "target-b-stays"
)
assert (
next(record for record in backend.records.values() if record["uri"] == source_b)["content"]
== "source-b-stays"
)
@pytest.mark.asyncio
async def test_copy_preserves_target_acl_even_when_enforcement_is_disabled():
source = "viking://resources/src.md"
target = "viking://resources/dst.md"
backend = _RealAclMemoryTransferBackend(
[
_record(
"source-file", source, acl_mode="restricted", acl_direct_grants=["7:user:alice"]
),
_record("source-chunk", f"{source}#chunk_0001"),
_record(
"target-file",
target,
acl_mode="inherit",
acl_direct_grants=["7:user:bob"],
acl_inherited_grants=[],
),
]
)
backend.acl_manager._runtime_config.get_account = AsyncMock(
return_value=SimpleNamespace(enabled=False)
)
await backend.copy_uri_mapping(_ctx(), source, target, recursive=False)
targets = _records_under(backend, target, recursive=False)
assert {record["uri"] for record in targets} == {target}
assert "source-chunk" in backend.records
assert all(record["acl_direct_grants"] == ["7:user:bob"] for record in targets)
assert all(record["acl_inherited_grants"] == [] for record in targets)
@pytest.mark.asyncio
async def test_copy_target_without_direct_acl_keeps_parent_inheritance():
source = "viking://resources/src.md"
parent = "viking://resources/team"
target = f"{parent}/dst.md"
inherited = ["3:group:editors"]
backend = _RealAclMemoryTransferBackend(
[
_record("source-file", source),
_record(
"parent",
parent,
acl_mode="inherit",
acl_direct_grants=inherited,
acl_inherited_grants=[],
),
_record(
"target-file",
target,
acl_mode="inherit",
acl_direct_grants=[],
acl_inherited_grants=inherited,
),
]
)
await backend.copy_uri_mapping(_ctx(), source, target, recursive=False)
copied = _records_under(backend, target, recursive=False)
assert len(copied) == 1
assert copied[0]["acl_direct_grants"] == []
assert copied[0]["acl_inherited_grants"] == inherited
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
@pytest.mark.parametrize("recursive,level", [(False, 2), (True, 0)])
@pytest.mark.parametrize("private", [False, True])
async def test_unindexed_source_preserves_target_records_and_acl(
transfer_method, recursive, level, private
):
source = "viking://resources/source"
target = "viking://resources/target"
backend = _RealAclMemoryTransferBackend(
[
_record(
"target-record",
target,
level=level,
abstract="old abstract",
acl_mode="restricted" if private else "none",
acl_direct_grants=["7:user:bob"] if private else [],
acl_inherited_grants=[],
),
_record("target-chunk", f"{target}#chunk_0001"),
]
)
original_records = dict(backend.records)
result = await getattr(backend, transfer_method)(
_ctx(), source, target, recursive=recursive, source_uris=[source]
)
assert result.scanned == result.written == result.deleted == 0
assert backend.records == original_records
assert backend.delete_calls == backend.upsert_calls == 0
assert backend.acl_manager is not None
effective = await backend.acl_manager.resolve(target, _ctx())
assert effective.context_fields() == {
"acl_mode": "restricted" if private else "inherit",
"acl_direct_grants": ["7:user:bob"] if private else [],
"acl_inherited_grants": [] if private else ["7:user:*"],
}
@pytest.mark.asyncio
async def test_copy_private_entry_skips_shared_resource_acl_resolution():
source = "viking://user/alice/resources/src.md"
target = "viking://user/alice/resources/dst.md"
backend = _RealAclMemoryTransferBackend(
[
_record("source-file", source, content="new"),
_record("target-file", target, content="old"),
]
)
await backend.copy_uri_mapping(_ctx(), source, target, recursive=False)
copied = _records_under(backend, target, recursive=False)
assert len(copied) == 1
assert copied[0]["content"] == "new"
@pytest.mark.asyncio
async def test_copy_directory_preserves_root_acl_and_inherits_it_to_new_entries():
source = "viking://resources/source"
target = "viking://resources/target"
source_child = f"{source}/child"
source_file = f"{source_child}/file.md"
target_child = f"{target}/child"
target_file = f"{target_child}/file.md"
unique_target = f"{target}/unique.md"
root_acl = ["7:user:bob"]
backend = _RealAclMemoryTransferBackend(
[
_record(
"source-root",
source,
level=0,
acl_mode="restricted",
acl_direct_grants=["7:user:alice"],
),
_record(
"source-child", source_child, level=0, acl_mode="restricted", acl_direct_grants=[]
),
_record("source-file", source_file),
_record(
"target-root",
target,
level=0,
acl_mode="restricted",
acl_direct_grants=root_acl,
acl_inherited_grants=[],
),
# Another index level can still carry an older ACL snapshot.
_record(
"target-root-l1",
target,
level=1,
acl_mode="restricted",
acl_direct_grants=["1:user:carol"],
acl_inherited_grants=[],
),
_record(
"unique-target",
unique_target,
acl_mode="inherit",
acl_direct_grants=["3:user:carol"],
acl_inherited_grants=root_acl,
),
]
)
await backend.copy_uri_mapping(
_ctx(),
source,
target,
recursive=True,
source_uris=[source, source_child, source_file],
)
by_uri = {record["uri"]: record for record in _records_under(backend, target)}
assert by_uri[target]["acl_direct_grants"] == root_acl
assert by_uri[target]["acl_inherited_grants"] == []
for uri in (target_child, target_file):
assert by_uri[uri]["acl_direct_grants"] == []
assert by_uri[uri]["acl_inherited_grants"] == root_acl
assert by_uri[unique_target]["acl_direct_grants"] == ["3:user:carol"]
assert by_uri[unique_target]["acl_inherited_grants"] == root_acl
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
@pytest.mark.parametrize(
("source", "target"),
[
("viking://resources/same", "viking://resources/same"),
("viking://resources/parent", "viking://resources/parent/child"),
("viking://resources/parent/child", "viking://resources/parent"),
],
)
async def test_uri_mapping_rejects_equal_or_containing_scopes(transfer_method, source, target):
backend = _MemoryTransferBackend([_record("source", source)])
with pytest.raises(InvalidArgumentError):
await getattr(backend, transfer_method)(_ctx(), source, target, recursive=True)
assert backend.upsert_calls == 0
assert list(backend.records) == ["source"]
@pytest.mark.asyncio
async def test_copy_uri_mapping_removes_partial_target_when_write_fails():
source = "viking://resources/src"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
]
)
backend.fail_upsert_at = 3
with pytest.raises(RuntimeError, match="injected vector write failure"):
await backend.copy_uri_mapping(_ctx(), source, "viking://resources/dst", recursive=True)
assert len(_records_under(backend, source)) == 3
assert _records_under(backend, "viking://resources/dst") == []
@pytest.mark.asyncio
async def test_copy_uri_mapping_reports_actual_residual_after_cleanup_failure():
source = "viking://resources/src"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
]
)
backend.fail_upsert_at = 3
backend.fail_delete_at = 1
backend.partial_delete_count = 1
with pytest.raises(VectorTransferRollbackError) as exc_info:
await backend.copy_uri_mapping(_ctx(), source, "viking://resources/dst", recursive=True)
assert exc_info.value.phase == "copy_target_cleanup"
assert exc_info.value.residual_count == 1
assert len(_records_under(backend, "viking://resources/dst")) == 1
@pytest.mark.asyncio
@pytest.mark.parametrize("transfer_method", ["copy_uri_mapping", "update_uri_mapping"])
async def test_uri_mapping_cleanup_residual_excludes_unaffected_target_records(
transfer_method,
):
source = "viking://resources/src"
target = "viking://resources/dst"
unique_target = f"{target}/unique.md"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
_record("unique-target", unique_target),
]
)
backend.fail_upsert_at = 3
backend.fail_delete_at = 1
backend.partial_delete_count = 1
with pytest.raises(VectorTransferRollbackError) as exc_info:
await getattr(backend, transfer_method)(_ctx(), source, target, recursive=True)
assert exc_info.value.residual_count == 1
assert any(record["uri"] == unique_target for record in backend.records.values())
@pytest.mark.asyncio
async def test_copy_uri_mapping_reports_rollback_when_delete_returns_zero():
source = "viking://resources/src"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
]
)
backend.fail_upsert_at = 3
backend.drop_delete_requests = True
with pytest.raises(VectorTransferRollbackError) as exc_info:
await backend.copy_uri_mapping(_ctx(), source, "viking://resources/dst", recursive=True)
assert exc_info.value.phase == "copy_target_cleanup"
assert exc_info.value.residual_count == 2
@pytest.mark.asyncio
async def test_update_uri_mapping_deletes_source_only_after_targets_exist():
source = "viking://resources/src"
backend = _MemoryTransferBackend(
[
_record("source-root", source, created_at=5, updated_at=6, active_count=7),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
]
)
result = await backend.update_uri_mapping(
_ctx(), source, "viking://resources/dst", recursive=True
)
assert result.scanned == 3
assert result.written == 3
assert result.deleted == 3
assert _records_under(backend, source) == []
targets = _records_under(backend, "viking://resources/dst")
assert len(targets) == 3
root = next(record for record in targets if record["uri"] == "viking://resources/dst")
assert (root["created_at"], root["updated_at"], root["active_count"]) == (5, 6, 7)
@pytest.mark.asyncio
async def test_update_uri_mapping_preserves_target_acl_and_inherits_new_entries():
source, target = "viking://resources/src", "viking://resources/dst"
backend = _RealAclMemoryTransferBackend(
[
_record("source", source, acl_mode="restricted", acl_direct_grants=["7:user:alice"]),
_record(
"source-child", f"{source}/child.md", acl_mode="restricted", acl_direct_grants=[]
),
_record("target", target, acl_mode="inherit", acl_direct_grants=["7:user:bob"]),
]
)
result = await backend.update_uri_mapping(_ctx(), source, target, recursive=True)
moved = sorted(_records_under(backend, target), key=lambda record: record["uri"])
assert [record["acl_mode"] for record in moved] == ["inherit", "inherit"]
assert [record["acl_direct_grants"] for record in moved] == [["7:user:bob"], []]
assert moved[1]["acl_inherited_grants"] == ["7:user:*", "7:user:bob"]
assert _records_under(backend, source) == []
await backend.update_uri_mapping(
_ctx(), target, source, recursive=True, restore_acl=result.source_acl
)
restored = sorted(_records_under(backend, source), key=lambda record: record["uri"])
assert [record["acl_direct_grants"] for record in restored] == [["7:user:alice"], []]
assert all(record["acl_mode"] == "restricted" for record in restored)
@pytest.mark.asyncio
async def test_update_uri_mapping_restores_source_and_removes_target_after_partial_delete():
source = "viking://resources/src"
backend = _MemoryTransferBackend(
[
_record("source-root", source),
_record("source-a", f"{source}/a.md"),
_record("source-b", f"{source}/b.md"),
]
)
backend.fail_delete_at = 1
backend.partial_delete_count = 1
with pytest.raises(RuntimeError, match="injected vector delete failure"):
await backend.update_uri_mapping(_ctx(), source, "viking://resources/dst", recursive=True)
assert len(_records_under(backend, source)) == 3
assert _records_under(backend, "viking://resources/dst") == []
@pytest.mark.asyncio
async def test_update_uri_mapping_rollback_restores_source_direct_acl():
source = "viking://resources/src"
target = "viking://resources/dst"
backend = _RealAclMemoryTransferBackend(
[
_record(
"source-root",
source,
acl_mode="inherit",
acl_direct_grants=["7:user:alice"],
acl_inherited_grants=["1:group:source-readers"],
),
_record(
"source-child",
f"{source}/child.md",
acl_mode="inherit",
acl_direct_grants=["3:user:bob"],
acl_inherited_grants=["7:user:alice"],
),
]
)
backend.fail_delete_at = 1
backend.partial_delete_count = 1
with pytest.raises(RuntimeError, match="injected vector delete failure"):
await backend.update_uri_mapping(_ctx(), source, target, recursive=True)
restored = sorted(_records_under(backend, source), key=lambda item: item["uri"])
assert [record["acl_direct_grants"] for record in restored] == [
["7:user:alice"],
["3:user:bob"],
]
assert _records_under(backend, target) == []
@pytest.mark.asyncio
async def test_update_uri_mapping_returns_empty_result_when_source_has_no_vectors():
backend = _MemoryTransferBackend([_record("outside", "viking://resources/other.md")])
result = await backend.update_uri_mapping(
_ctx(),
"viking://resources/missing.md",
"viking://resources/dst.md",
recursive=False,
)
assert result.scanned == 0
assert result.written == 0
assert result.deleted == 0
@pytest.mark.asyncio
@pytest.mark.parametrize("operation", ["copy_uri_mapping", "update_uri_mapping"])
@pytest.mark.parametrize("mode", ["local", "volcengine", "vikingdb"])
@pytest.mark.parametrize("incoming_chunk", [False, True])
async def test_target_chunk_candidate_respects_filesystem_entry(operation, mode, incoming_chunk):
source, target = "viking://resources/source.md", "viking://resources/target.md"
sibling = target + "#chunk-1"
records = [_record("source", source), _record("private", sibling)]
if incoming_chunk:
records.append(_record("source-chunk", source + "#chunk-1"))
backend = _MemoryTransferBackend(records)
backend.backend_mode = mode
exists = AsyncMock(return_value=True)
await getattr(backend, operation)(_ctx(), source, target, target_entry_exists=exists)
assert any(record["uri"] == target for record in backend.records.values())
assert backend.records["private"] == records[1]
if incoming_chunk:
assert backend.records["source-chunk"] == records[2]
@pytest.mark.asyncio
async def test_transfer_does_not_inspect_unrelated_chunk_shaped_entry():
source, target = "viking://resources/source.md", "viking://resources/target.md"
backend = _MemoryTransferBackend(
[_record("source", source), _record("old", target + "#chunk-1")]
)
result = await backend.copy_uri_mapping(
_ctx(),
source,
target,
target_entry_exists=AsyncMock(side_effect=RuntimeError("unrelated stat failed")),
)
assert result.written == 1
assert backend.records["old"]["uri"] == target + "#chunk-1"