Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

35.7 KB
Raw Blame
from __future__ import annotations

import json
from types import SimpleNamespace
from typing import Any
from unittest.mock import AsyncMock, MagicMock

import pytest

from xagent.core.tools.core.RAG_tools.core.schemas import (
    IngestionResult,
    IngestionStepResult,
    WebIngestionResult,
)
from xagent.core.tools.core.RAG_tools.kb import (
    KBApiCompatibilityFacade,
    KBApiFailedIngestCleanupDecision,
    KBApiOperationResult,
)
from xagent.web.api import kb as kb_module
from xagent.web.models.user import User


class _Facade:
    def __init__(self) -> None:
        self.rollback_complete_inputs: list[tuple[KBApiOperationResult[Any], bool]] = []
        self.single_cleanup_inputs: list[
            tuple[KBApiOperationResult[Any], int | None]
        ] = []
        self.batch_cleanup_inputs: list[
            tuple[list[KBApiOperationResult[Any]], int | None]
        ] = []

    def with_rollback_complete(
        self,
        api_result: KBApiOperationResult[Any],
        rollback_complete: bool,
    ) -> KBApiOperationResult[Any]:
        self.rollback_complete_inputs.append((api_result, rollback_complete))
        return KBApiOperationResult(
            result=api_result.result,
            operation_outcome=api_result.operation_outcome,
            rollback_complete=rollback_complete,
        )

    def failed_ingest_cleanup_decision(
        self,
        api_result: KBApiOperationResult[Any],
        *,
        successful_documents: int | None = None,
    ) -> Any:
        self.single_cleanup_inputs.append((api_result, successful_documents))
        return KBApiFailedIngestCleanupDecision(
            successful_documents=3,
            side_effects_may_remain=api_result.rollback_complete is False,
        )

    def failed_batch_ingest_cleanup_decision(
        self,
        api_results: list[KBApiOperationResult[Any]],
        *,
        successful_documents: int | None = None,
    ) -> Any:
        self.batch_cleanup_inputs.append((api_results, successful_documents))
        return KBApiFailedIngestCleanupDecision(
            successful_documents=5,
            side_effects_may_remain=True,
        )


@pytest.mark.asyncio
async def test_api_failed_ingest_config_cleanup_uses_api_outcome_decision(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    facade = _Facade()
    cleanup_calls: list[dict[str, Any]] = []
    monkeypatch.setattr(kb_module, "_get_api_compatibility_facade", lambda: facade)

    async def fake_cleanup(**kwargs: Any) -> None:
        cleanup_calls.append(kwargs)

    monkeypatch.setattr(
        kb_module,
        "_cleanup_collection_metadata_after_failed_ingest",
        fake_cleanup,
    )
    api_result = KBApiOperationResult(
        result=IngestionResult(status="error", message="failed")
    )
    user = User()
    user.id = 7

    await kb_module._cleanup_collection_metadata_after_failed_api_ingest(
        api_result=api_result,
        collection_existed_before=True,
        collection_name="demo",
        user=user,
        context="ingest",
        successful_documents=1,
        rollback_complete=False,
    )

    assert facade.rollback_complete_inputs == [(api_result, False)]
    # The decision reads the result carrying the rollback outcome, not the input.
    assert len(facade.single_cleanup_inputs) == 1
    decided_on, decided_documents = facade.single_cleanup_inputs[0]
    assert decided_on.rollback_complete is False
    assert decided_documents == 1
    assert cleanup_calls == [
        {
            "collection_existed_before": True,
            "collection_name": "demo",
            "user": user,
            "context": "ingest",
            "decision": KBApiFailedIngestCleanupDecision(
                successful_documents=3,
                side_effects_may_remain=True,
            ),
        }
    ]


@pytest.mark.asyncio
async def test_api_failed_batch_ingest_config_cleanup_uses_api_outcome_decision(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    facade = _Facade()
    cleanup_calls: list[dict[str, Any]] = []
    monkeypatch.setattr(kb_module, "_get_api_compatibility_facade", lambda: facade)

    async def fake_cleanup(**kwargs: Any) -> None:
        cleanup_calls.append(kwargs)

    monkeypatch.setattr(
        kb_module,
        "_cleanup_collection_metadata_after_failed_ingest",
        fake_cleanup,
    )
    api_results = [
        KBApiOperationResult(result=IngestionResult(status="success", message="ok")),
        KBApiOperationResult(result=IngestionResult(status="error", message="failed")),
    ]
    user = User()
    user.id = 9

    await kb_module._cleanup_collection_metadata_after_failed_batch_api_ingest(
        api_results=api_results,
        collection_existed_before=False,
        collection_name="demo",
        user=user,
        context="ingest_cloud",
        successful_documents=1,
    )

    assert facade.batch_cleanup_inputs == [(api_results, 1)]
    assert cleanup_calls == [
        {
            "collection_existed_before": False,
            "collection_name": "demo",
            "user": user,
            "context": "ingest_cloud",
            "decision": KBApiFailedIngestCleanupDecision(
                successful_documents=5,
                side_effects_may_remain=True,
            ),
        }
    ]


def test_background_failed_ingest_config_cleanup_reuses_api_helper(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from xagent.web.jobs import kb_tasks

    api_result = KBApiOperationResult(
        result=IngestionResult(status="error", message="failed")
    )
    user = User()
    user.id = 11
    db = object()
    calls: list[dict[str, Any]] = []
    monkeypatch.setattr(kb_tasks, "_get_job_user", lambda *args, **kwargs: user)

    async def fake_api_helper(**kwargs: Any) -> None:
        calls.append(kwargs)

    monkeypatch.setattr(
        kb_module,
        "_cleanup_collection_metadata_after_failed_api_ingest",
        fake_api_helper,
    )

    kb_tasks._cleanup_failed_job_collection_metadata_after_api_ingest(
        db,  # type: ignore[arg-type]
        {
            "collection": "job-kb",
            "collection_existed_before": False,
        },
        api_result=api_result,
        context="background document ingest",
        successful_documents=2,
        rollback_complete=True,
    )

    assert calls == [
        {
            "api_result": api_result,
            "collection_existed_before": False,
            "collection_name": "job-kb",
            "user": user,
            "context": "background document ingest",
            "successful_documents": 2,
            "rollback_complete": True,
        }
    ]


def test_background_web_cleanup_keeps_early_exception_fallback(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from xagent.web.jobs import kb_tasks

    fallback = MagicMock()
    api_helper = MagicMock()
    db = object()
    payload = {"collection": "job-kb"}
    monkeypatch.setattr(
        kb_tasks,
        "_cleanup_failed_job_collection_metadata",
        fallback,
    )
    monkeypatch.setattr(
        kb_tasks,
        "_cleanup_failed_job_collection_metadata_after_api_ingest",
        api_helper,
    )

    kb_tasks._cleanup_failed_web_collection_metadata_if_new(
        db,  # type: ignore[arg-type]
        payload,
    )

    fallback.assert_called_once_with(
        db,
        payload,
        context="background web ingest",
    )
    api_helper.assert_not_called()


def _records_lookup(records: Any):
    """Stub for the facade's list_document_records driving failure-time decisions."""

    def _lookup(**kwargs: Any) -> Any:
        if isinstance(records, Exception):
            raise records
        return records

    return _lookup


@pytest.mark.parametrize(
    ("records", "on_error", "expected"),
    [
        ([{"file_id": "sibling"}], True, True),
        ([], True, False),
        # A store read that fails must not authorize a delete...
        (RuntimeError("vector store down"), True, True),
        # ...nor make a possibly empty knowledge base visible.
        (RuntimeError("vector store down"), False, False),
    ],
)
def test_collection_holds_documents_reads_at_decision_time(
    records: Any,
    on_error: bool,
    expected: bool,
) -> None:
    facade = _facade_with(list_document_records=_records_lookup(records))

    assert (
        facade.collection_holds_documents(
            collection_name="shared-kb",
            user_id=3,
            context="test",
            on_error=on_error,
        )
        is expected
    )


@pytest.mark.parametrize(
    ("stored_config", "expected"),
    [
        ('{"chunk_size": 512}', True),
        (None, False),
        (RuntimeError("config store down"), True),
    ],
)
@pytest.mark.asyncio
async def test_collection_config_exists_reads_at_decision_time(
    stored_config: Any,
    expected: bool,
) -> None:
    async def _get_collection_config(**kwargs: Any) -> Any:
        if isinstance(stored_config, Exception):
            raise stored_config
        return stored_config

    facade = _facade_with(get_collection_config=_get_collection_config)

    assert (
        await facade._collection_config_exists(
            collection_name="shared-kb",
            user_id=3,
            context="test",
        )
        is expected
    )


@pytest.mark.asyncio
async def test_rollback_keeps_collection_holding_a_sibling_document(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A stale collection_existed_before must not delete a sibling job's work."""
    from pathlib import Path

    delete_collection = MagicMock()
    store = MagicMock()
    # A sibling document: same file_id (both ingests upserted the same path),
    # different doc_id.
    store.list_document_records.return_value = [
        {"file_id": "file-1", "doc_id": "sibling-doc"}
    ]
    monkeypatch.setattr(kb_module, "get_vector_index_store", lambda: store)
    monkeypatch.setattr(kb_module, "delete_collection", delete_collection)
    monkeypatch.setattr(kb_module, "_restore_ingest_file_backup", MagicMock())
    monkeypatch.setattr(kb_module, "clear_ingestion_status", MagicMock())

    user = User()
    user.id = 5
    user.is_admin = False
    file_record = MagicMock()
    file_record.file_id = "file-1"

    await kb_module._rollback_failed_ingestion(
        db=MagicMock(),
        user=user,
        collection_name="shared-kb",
        result=IngestionResult(status="error", message="failed", doc_id="my-doc"),
        file_path=Path("/tmp/does-not-matter.pdf"),
        file_record=file_record,
        collection_existed_before=False,
        uploaded_file_existed_before=True,
        file_backup_path=None,
        had_existing_file=False,
    )

    delete_collection.assert_not_called()


@pytest.mark.asyncio
async def test_rollback_keeps_collection_whose_config_a_sibling_published(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Two ingests of the same path share a doc_id, so config is the second guard."""
    from pathlib import Path

    delete_collection = MagicMock()
    store = MagicMock()
    store.list_document_records.return_value = [
        {"file_id": "file-1", "doc_id": "my-doc"}
    ]
    monkeypatch.setattr(kb_module, "get_vector_index_store", lambda: store)
    monkeypatch.setattr(kb_module, "delete_collection", delete_collection)
    monkeypatch.setattr(kb_module, "_restore_ingest_file_backup", MagicMock())
    monkeypatch.setattr(kb_module, "clear_ingestion_status", MagicMock())
    monkeypatch.setattr(
        kb_module,
        "delete_document",
        MagicMock(return_value=SimpleNamespace(status="success")),
    )

    async def _published(**kwargs: Any) -> str:
        return '{"chunk_size": 512}'

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(get_collection_config=_published),
    )

    user = User()
    user.id = 5
    user.is_admin = False
    file_record = MagicMock()
    file_record.file_id = "file-1"

    await kb_module._rollback_failed_ingestion(
        db=MagicMock(),
        user=user,
        collection_name="shared-kb",
        result=IngestionResult(
            status="error",
            message="failed",
            doc_id="my-doc",
            completed_steps=[
                {"name": "register_document", "metadata": {"created": True}}
            ],
        ),
        file_path=Path("/tmp/does-not-matter.pdf"),
        file_record=file_record,
        collection_existed_before=False,
        uploaded_file_existed_before=True,
        file_backup_path=None,
        had_existing_file=False,
    )

    delete_collection.assert_not_called()


@pytest.mark.asyncio
async def test_cleanup_keeps_metadata_when_the_collection_holds_documents(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The stamped flag is stale; a config-only ghost holds no documents."""
    delete_metadata = AsyncMock()
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=_records_lookup([{"file_id": "sibling"}]),
            delete_collection_metadata=delete_metadata,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._cleanup_failed_new_collection_metadata(
        collection_name="shared-kb",
        user=user,
    )

    delete_metadata.assert_not_awaited()


@pytest.mark.asyncio
async def test_cleanup_removes_a_config_only_ghost(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A collection with no documents is the ghost this cleanup exists for."""
    delete_metadata = AsyncMock(return_value={"config_rows": 1})
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=_records_lookup([]),
            delete_collection_metadata=delete_metadata,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._cleanup_failed_new_collection_metadata(
        collection_name="ghost-kb",
        user=user,
    )

    delete_metadata.assert_awaited_once()


def _web_result(documents_created: int) -> WebIngestionResult:
    return WebIngestionResult(
        status="success",
        collection="web-kb",
        total_urls_found=documents_created,
        pages_crawled=documents_created,
        pages_failed=0,
        documents_created=documents_created,
        chunks_created=documents_created,
        embeddings_created=documents_created,
        message="crawl completed",
        elapsed_time_ms=0,
    )


@pytest.mark.parametrize(
    ("collection_existed_before", "expected_outcome"),
    [(False, "the knowledge base was not created"), (True, "nothing was added")],
)
def test_empty_ingest_is_demoted_to_error(
    monkeypatch: pytest.MonkeyPatch,
    collection_existed_before: bool,
    expected_outcome: str,
) -> None:
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: type(
            "F",
            (),
            {
                "with_result": staticmethod(
                    lambda api_result, result: KBApiOperationResult(
                        result=result,
                        operation_outcome=api_result.operation_outcome,
                        rollback_complete=api_result.rollback_complete,
                    )
                )
            },
        )(),
    )
    api_result = KBApiOperationResult(result=_web_result(0))

    api_result = KBApiOperationResult(result=api_result.result, rollback_complete=False)
    demoted_result = kb_module._demote_empty_crawl_to_error(
        api_result,
        collection_existed_before=collection_existed_before,
    )
    demoted = demoted_result.result

    assert demoted.status == "error"
    assert expected_outcome in demoted.message
    # The cleanup decision reads rollback_complete, so demotion must not drop it.
    assert demoted_result.rollback_complete is False


def test_successful_ingest_is_not_demoted() -> None:
    api_result = KBApiOperationResult(result=_web_result(2))

    assert (
        kb_module._demote_empty_crawl_to_error(
            api_result, collection_existed_before=False
        )
        is api_result
    )


def test_job_config_save_failure_is_not_retryable(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Retrying after the documents landed would delete the collection."""
    from xagent.core.tools.core.RAG_tools.core.schemas import IngestionConfig
    from xagent.web.jobs import kb_tasks
    from xagent.web.jobs.exceptions import BackgroundJobHandlerError

    user = User()
    user.id = 13
    monkeypatch.setattr(kb_tasks, "_get_job_user", lambda *args, **kwargs: user)

    async def fail_save(**kwargs: Any) -> None:
        raise kb_module.CollectionConfigSaveError("config store down")

    monkeypatch.setattr(kb_module, "_save_collection_config_after_ingest", fail_save)

    with pytest.raises(BackgroundJobHandlerError) as excinfo:
        kb_tasks._save_job_collection_config_after_ingest(
            MagicMock(),
            {"collection": "job-kb", "user_id": 13},
            IngestionConfig(),
            context="background document ingest",
            documents_created=1,
        )

    assert excinfo.value.retryable is False


@pytest.mark.parametrize(
    ("existing", "expected_extras"),
    [
        (
            '{"chunk_size": 111, "rerank_model_id": "bge-reranker"}',
            {"rerank_model_id": "bge-reranker"},
        ),
        ('{"chunk_size": 111}', {}),
        (None, {}),
        ("not json", {}),
    ],
)
@pytest.mark.asyncio
async def test_config_merge_keeps_settings_this_ingest_does_not_own(
    monkeypatch: pytest.MonkeyPatch,
    existing: Any,
    expected_extras: dict[str, Any],
) -> None:
    """A rerank binding saved while the ingest ran must survive the config write."""

    async def _get_collection_config(**kwargs: Any) -> Any:
        return existing

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: type(
            "F", (), {"get_collection_config": staticmethod(_get_collection_config)}
        )(),
    )

    merged = json.loads(
        await kb_module._config_json_preserving_extras(
            collection="kb",
            config_json='{"chunk_size": 2048}',
            user_id=1,
            context="test",
            collection_existed_before=True,
        )
    )

    assert merged["chunk_size"] == 2048
    for key, value in expected_extras.items():
        assert merged[key] == value
    if not expected_extras:
        assert set(merged) == {"chunk_size"}


@pytest.mark.asyncio
async def test_config_save_failure_does_not_claim_the_import_must_be_retried(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The documents are listed, so re-importing would only duplicate them."""

    async def _failing_save(**kwargs: Any) -> None:
        raise RuntimeError("config store down")

    async def _no_existing_config(**kwargs: Any) -> None:
        return None

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: type(
            "F",
            (),
            {
                "save_collection_config": staticmethod(_failing_save),
                "get_collection_config": staticmethod(_no_existing_config),
            },
        )(),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    with pytest.raises(kb_module.CollectionConfigSaveError) as excinfo:
        await kb_module._save_collection_config_after_ingest(
            collection="q3",
            config_json='{"chunk_size": 2048}',
            user=user,
            context="ingest",
            documents_created=1,
        )

    message = str(excinfo.value)
    assert "Do not re-import" in message
    assert "stays hidden" not in message


@pytest.mark.parametrize(
    ("collection_existed_before", "should_publish"),
    [(False, True), (True, False)],
)
@pytest.mark.asyncio
async def test_documents_left_by_an_incomplete_rollback_are_published(
    monkeypatch: pytest.MonkeyPatch,
    collection_existed_before: bool,
    should_publish: bool,
) -> None:
    """Documents with no config row are invisible and block the name.

    A pre-existing collection is exempt: republishing would overwrite settings
    its previous import saved.
    """
    save = AsyncMock()

    async def _no_existing_config(**kwargs: Any) -> None:
        return None

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=_records_lookup([{"file_id": "leftover"}]),
            save_collection_config=save,
            get_collection_config=_no_existing_config,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._save_collection_config_after_ingest(
        collection="kb",
        config_json='{"chunk_size": 2048}',
        user=user,
        context="ingest_web",
        documents_created=0,
        collection_existed_before=collection_existed_before,
    )

    assert save.await_count == (1 if should_publish else 0)


@pytest.mark.parametrize(
    ("payload", "expected"),
    [({}, True), ({"collection_existed_before": False}, False)],
)
def test_missing_flag_defaults_to_pre_existing(
    payload: dict[str, Any], expected: bool
) -> None:
    """An absent flag must not authorize cleanup of someone else's collection."""
    from xagent.web.jobs import kb_tasks

    assert kb_tasks._collection_existed_before(payload) is expected


@pytest.mark.parametrize(
    ("status", "registered", "expected"),
    [
        # A registered document is listed and deletable even with no chunks.
        ("success", True, 1),
        ("partial", True, 1),
        # Nothing was registered, so nothing landed.
        ("success", False, 0),
        ("error", True, 0),
    ],
)
def test_produced_documents_is_the_shared_publish_predicate(
    status: str, registered: bool, expected: int
) -> None:
    result = IngestionResult(
        status=status,
        message="m",
        completed_steps=[IngestionStepResult(name="register_document", metadata={})]
        if registered
        else [],
    )

    assert result.produced_documents == expected


def _facade_with(**attrs: Any) -> Any:
    """The real facade decisions over the stubbed store calls in `attrs`."""
    return type(
        "F", (KBApiCompatibilityFacade,), {k: staticmethod(v) for k, v in attrs.items()}
    )()


@pytest.mark.asyncio
async def test_metadata_cleanup_deletes_with_the_scope_it_read(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """An admin-scoped delete would wipe a row another tenant owns by name."""
    list_records = MagicMock(return_value=[])
    delete_metadata = AsyncMock(return_value={"config_rows": 1})
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=list_records,
            delete_collection_metadata=delete_metadata,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = True

    await kb_module._cleanup_failed_new_collection_metadata(
        collection_name="shared-kb",
        user=user,
    )

    list_records.assert_called_once_with(
        collection_name="shared-kb", user_id=5, is_admin=False, max_results=1
    )
    delete_metadata.assert_awaited_once_with(
        collection_name="shared-kb",
        user_id=5,
        is_admin=False,
        delete_orphaned_metadata=True,
    )


@pytest.mark.asyncio
async def test_publish_does_not_guess_when_the_store_read_fails(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """An unreadable store must not make a possibly empty KB visible."""
    save = AsyncMock()
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=_records_lookup(RuntimeError("vector store down")),
            save_collection_config=save,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._save_collection_config_after_ingest(
        collection="kb",
        config_json="{}",
        user=user,
        context="ingest_web",
        documents_created=0,
        collection_existed_before=False,
    )

    save.assert_not_awaited()


@pytest.mark.asyncio
async def test_cleanup_does_not_delete_when_the_store_read_fails(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The opposite direction: an unreadable store must not authorize a delete."""
    delete_metadata = AsyncMock()
    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            list_document_records=_records_lookup(RuntimeError("vector store down")),
            delete_collection_metadata=delete_metadata,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._cleanup_failed_new_collection_metadata(
        collection_name="kb",
        user=user,
    )

    delete_metadata.assert_not_awaited()


@pytest.mark.parametrize(
    ("existed_before", "records", "register_created", "config", "reads", "may_delete"),
    [
        (False, [], True, None, True, True),
        (False, [{"doc_id": "doc-1", "file_id": "f-1"}], True, None, True, True),
        # a sibling landed a document (same-path ingests share a file_id), or
        # published the config
        (False, [{"doc_id": "other", "file_id": "f-1"}], True, None, False, False),
        (
            False,
            [SimpleNamespace(doc_id="other", file_id="f-2")],
            True,
            None,
            False,
            False,
        ),
        (
            False,
            [
                {"doc_id": "doc-1", "file_id": "f-1"},
                {"doc_id": "other", "file_id": "f-1"},
            ],
            True,
            None,
            False,
            False,
        ),
        (False, [], True, "{}", True, False),
        (True, [], True, None, False, False),
        # a run that holds no document of its own counts every record
        (False, [{"doc_id": "doc-1", "file_id": "f-1"}], False, None, False, False),
    ],
)
@pytest.mark.asyncio
async def test_rollback_may_delete_collection_reads_live_state(
    existed_before: bool,
    records: list[Any],
    register_created: bool,
    config: Any,
    reads: bool,
    may_delete: bool,
) -> None:
    get_config = AsyncMock(return_value=config)
    facade = _facade_with(get_collection_config=get_config)

    assert (
        await facade.failed_ingest_may_delete_collection(
            collection_name="kb",
            user_id=5,
            collection_existed_before=existed_before,
            collection_records=records,
            register_created=register_created,
            doc_id="doc-1",
            context="test",
        )
        is may_delete
    )
    if reads:
        get_config.assert_awaited_once_with(collection="kb", user_id=5, is_admin=False)
    else:
        get_config.assert_not_awaited()


@pytest.mark.asyncio
async def test_rollback_keeps_the_collection_when_the_config_read_fails() -> None:
    """Unknown state must not authorize deleting a whole collection."""

    async def _get_collection_config(**kwargs: Any) -> Any:
        raise RuntimeError("metadata store down")

    facade = _facade_with(get_collection_config=_get_collection_config)

    assert (
        await facade.failed_ingest_may_delete_collection(
            collection_name="kb",
            user_id=5,
            collection_existed_before=False,
            collection_records=[],
            register_created=False,
            doc_id=None,
            context="test",
        )
        is False
    )


def test_job_config_save_failure_keeps_the_result_payload(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A FAILED job with no payload is indistinguishable from a real failure."""
    from xagent.core.tools.core.RAG_tools.core.schemas import IngestionConfig
    from xagent.web.jobs import kb_tasks
    from xagent.web.jobs.exceptions import BackgroundJobHandlerError

    user = User()
    user.id = 13
    monkeypatch.setattr(kb_tasks, "_get_job_user", lambda *args, **kwargs: user)

    async def fail_save(**kwargs: Any) -> None:
        raise kb_module.CollectionConfigSaveError("config store down")

    monkeypatch.setattr(kb_module, "_save_collection_config_after_ingest", fail_save)

    with pytest.raises(BackgroundJobHandlerError) as excinfo:
        kb_tasks._save_job_collection_config_after_ingest(
            MagicMock(),
            {"collection": "job-kb", "user_id": 13},
            IngestionConfig(),
            context="background document ingest",
            documents_created=1,
            result_payload={"file_id": "file-1", "status": "success"},
        )

    assert excinfo.value.retryable is False
    assert excinfo.value.result == {"file_id": "file-1", "status": "success"}


def test_job_with_a_missing_user_fails_instead_of_succeeding_silently(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Returning here would mark the job SUCCEEDED with nothing published."""
    from xagent.core.tools.core.RAG_tools.core.schemas import IngestionConfig
    from xagent.web.jobs import kb_tasks
    from xagent.web.jobs.exceptions import BackgroundJobHandlerError

    monkeypatch.setattr(kb_tasks, "_get_job_user", lambda *args, **kwargs: None)

    with pytest.raises(BackgroundJobHandlerError) as excinfo:
        kb_tasks._save_job_collection_config_after_ingest(
            MagicMock(),
            {"collection": "job-kb", "user_id": 13},
            IngestionConfig(),
            context="background document ingest",
            documents_created=1,
            result_payload={"file_id": "file-1"},
        )

    assert excinfo.value.retryable is False
    assert excinfo.value.result == {"file_id": "file-1"}


@pytest.mark.asyncio
async def test_unreadable_config_does_not_overwrite_an_existing_collection(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The write replaces the row wholesale, so writing blind would drop settings."""
    save = AsyncMock()

    async def _unreadable(**kwargs: Any) -> Any:
        raise RuntimeError("config store down")

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            save_collection_config=save, get_collection_config=_unreadable
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._save_collection_config_after_ingest(
        collection="kb",
        config_json='{"chunk_size": 2048}',
        user=user,
        context="ingest",
        documents_created=1,
        collection_existed_before=True,
    )

    save.assert_not_awaited()


@pytest.mark.asyncio
async def test_unreadable_config_still_publishes_a_new_collection(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """A brand-new collection has no settings to lose."""
    save = AsyncMock()

    async def _unreadable(**kwargs: Any) -> Any:
        raise RuntimeError("config store down")

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            save_collection_config=save, get_collection_config=_unreadable
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    await kb_module._save_collection_config_after_ingest(
        collection="kb",
        config_json='{"chunk_size": 2048}',
        user=user,
        context="ingest",
        documents_created=1,
        collection_existed_before=False,
    )

    save.assert_awaited_once()


def test_missing_user_is_ignored_when_there_is_nothing_to_publish(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Raising here would skip the caller's failure cleanup."""
    from xagent.core.tools.core.RAG_tools.core.schemas import IngestionConfig
    from xagent.web.jobs import kb_tasks

    get_user = MagicMock(return_value=None)
    monkeypatch.setattr(kb_tasks, "_get_job_user", get_user)

    kb_tasks._save_job_collection_config_after_ingest(
        MagicMock(),
        {"collection": "job-kb", "user_id": 13, "collection_existed_before": True},
        IngestionConfig(),
        context="background web ingest",
        documents_created=0,
    )

    get_user.assert_not_called()


def test_missing_user_on_a_failed_new_collection_does_not_raise(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """The caller's metadata cleanup runs after this; raising would orphan the row."""
    from xagent.core.tools.core.RAG_tools.core.schemas import IngestionConfig
    from xagent.web.jobs import kb_tasks

    monkeypatch.setattr(kb_tasks, "_get_job_user", lambda *args, **kwargs: None)

    kb_tasks._save_job_collection_config_after_ingest(
        MagicMock(),
        {"collection": "job-kb", "user_id": 13, "collection_existed_before": False},
        IngestionConfig(),
        context="background web ingest",
        documents_created=0,
    )


@pytest.mark.parametrize(
    ("existed_before", "expected"),
    [(True, "knowledge base settings"), (False, "not listed yet")],
)
@pytest.mark.asyncio
async def test_config_save_failure_advice_matches_what_the_user_can_do(
    monkeypatch: pytest.MonkeyPatch,
    existed_before: bool,
    expected: str,
) -> None:
    """A collection that was never published has no settings page to visit."""

    async def _failing_save(**kwargs: Any) -> None:
        raise RuntimeError("config store down")

    async def _no_existing_config(**kwargs: Any) -> None:
        return None

    monkeypatch.setattr(
        kb_module,
        "_get_api_compatibility_facade",
        lambda: _facade_with(
            save_collection_config=_failing_save,
            get_collection_config=_no_existing_config,
        ),
    )

    user = User()
    user.id = 5
    user.is_admin = False

    with pytest.raises(kb_module.CollectionConfigSaveError) as excinfo:
        await kb_module._save_collection_config_after_ingest(
            collection="q3",
            config_json='{"chunk_size": 2048}',
            user=user,
            context="ingest",
            documents_created=1,
            collection_existed_before=existed_before,
        )

    assert expected in str(excinfo.value)


@pytest.mark.asyncio
async def test_failed_ingest_config_cleanup_follows_the_cleanup_decision(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    cleaned: list[str] = []

    async def fake_cleanup(*, collection_name: str, user: Any) -> None:
        cleaned.append(collection_name)

    monkeypatch.setattr(
        kb_module, "_cleanup_failed_new_collection_metadata", fake_cleanup
    )
    user = User()
    user.id = 3

    await kb_module._cleanup_collection_metadata_after_failed_ingest(
        collection_existed_before=False,
        collection_name="demo",
        user=user,
        context="ingest",
        decision=SimpleNamespace(  # type: ignore[arg-type]
            keeps_new_collection_metadata=False,
            successful_documents=5,
            side_effects_may_remain=True,
        ),
    )

    assert cleaned == ["demo"]


@pytest.mark.asyncio
async def test_failed_ingest_config_cleanup_warns_when_side_effects_may_remain(
    monkeypatch: pytest.MonkeyPatch,
    caplog: pytest.LogCaptureFixture,
) -> None:
    cleaned: list[str] = []

    async def fake_cleanup(*, collection_name: str, user: Any) -> None:
        cleaned.append(collection_name)

    monkeypatch.setattr(
        kb_module, "_cleanup_failed_new_collection_metadata", fake_cleanup
    )
    caplog.set_level("WARNING", logger="xagent.web.api.kb")
    user = User()
    user.id = 3

    await kb_module._cleanup_collection_metadata_after_failed_ingest(
        collection_existed_before=False,
        collection_name="demo",
        user=user,
        context="ingest",
        decision=KBApiFailedIngestCleanupDecision(
            successful_documents=0,
            side_effects_may_remain=True,
        ),
    )

    assert cleaned == []
    assert [
        (record.levelname, record.getMessage())
        for record in caplog.records
        if record.name == "xagent.web.api.kb"
    ] == [
        (
            "WARNING",
            "Skipping failed-ingest collection metadata cleanup for demo/user_3 "
            "during ingest because rollback side effects may remain",
        )
    ]