Skip to content

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

66.2 KB
Raw Blame
# 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"