Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

111 KB
Raw Blame
from __future__ import annotations

from collections import deque
from collections.abc import Callable, Generator, Sequence
from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import UTC, datetime, timedelta
from typing import Literal, Never, override
from unittest.mock import patch

import pytest
from pydantic import BaseModel, JsonValue
from typing_extensions import TypedDict

from services.knowledge_fs import data_facade as data_facade_module
from services.knowledge_fs.capability_broker import KnowledgeFSIssuedProductCapability
from services.knowledge_fs.data_facade import KnowledgeFSDataFacade
from services.knowledge_fs.product_dto import (
    KnowledgeFSAdmittedQueryRequest,
    KnowledgeFSCatQuery,
    KnowledgeFSDiffQuery,
    KnowledgeFSDocumentDeletePayload,
    KnowledgeFSDocumentResponse,
    KnowledgeFSDocumentRevisionListResponse,
    KnowledgeFSDocumentRevisionResponse,
    KnowledgeFSFindQuery,
    KnowledgeFSGoldenQuestionBulkImportPayload,
    KnowledgeFSGoldenQuestionBulkImportRowPayload,
    KnowledgeFSGoldenQuestionEvidenceMatchPayload,
    KnowledgeFSGoldenQuestionPayload,
    KnowledgeFSGrepQuery,
    KnowledgeFSListQuery,
    KnowledgeFSLogicalDocumentDeletePayload,
    KnowledgeFSLogicalDocumentResponse,
    KnowledgeFSMetadataFieldCreatePayload,
    KnowledgeFSMetadataFieldUpdatePayload,
    KnowledgeFSProductRerankProfile,
    KnowledgeFSProductRetrievalProfile,
    KnowledgeFSProductScoreThreshold,
    KnowledgeFSProfileModelSelection,
    KnowledgeFSQueryCreatePayload,
    KnowledgeFSResearchTaskCreatePayload,
    KnowledgeFSSettingsPayload,
    KnowledgeFSSourceCreatePayload,
    KnowledgeFSSourceUpdatePayload,
    KnowledgeFSSpaceUpdatePayload,
    KnowledgeFSStatQuery,
    KnowledgeFSTechnicalSummary,
    KnowledgeFSTreeQuery,
    KnowledgeFSUploadPartPresignPayload,
    KnowledgeFSUploadSessionAbortPayload,
    KnowledgeFSUploadSessionCompletePayload,
    KnowledgeFSUploadSessionCreatePayload,
    KnowledgeFSUploadSessionPartPayload,
)
from services.knowledge_fs.product_remote import (
    KnowledgeFSOperationUnavailableError,
    KnowledgeFSProductRemoteError,
    KnowledgeFSProductRequestRejectedError,
    KnowledgeFSProductResourceNotFoundError,
    KnowledgeFSRemoteBinaryRequest,
    KnowledgeFSRemoteJSONRequest,
    KnowledgeFSRemoteMultipartFile,
    KnowledgeFSRemoteMultipartRequest,
    KnowledgeFSRemoteSSERequest,
    KnowledgeFSRemoteSSEResponse,
)
from services.knowledge_fs.query_images import KnowledgeFSQueryImagePreview
from services.knowledge_fs.service_api_authorization import KnowledgeFSServiceApiProfile
from tests.helpers.unit.services.knowledge_fs_fakes import UnexpectedCapabilityIssuer
from tests.helpers.unit.services.knowledge_fs_services_a_fakes import CallRecorder, RecordedCall


class _FacadeScope(TypedDict, closed=True):
    tenant_id: str
    account_id: str
    control_space_id: str


class FailingBroker(UnexpectedCapabilityIssuer):
    def __init__(self) -> None:
        self.calls = 0

    @override
    def issue_interactive(self, **kwargs: object) -> Never:
        _ = kwargs
        self.calls += 1
        raise AssertionError("manifest gaps must fail before capability issuance")


class FailingRemote:
    def __init__(self) -> None:
        self.calls = 0

    def batch_space_summaries(self, **kwargs: object) -> Never:
        _ = kwargs
        self.calls += 1
        raise AssertionError("not used")

    def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> Never:
        _ = request
        self.calls += 1
        raise AssertionError("manifest gaps must fail before external I/O")

    def execute_binary(self, request: KnowledgeFSRemoteBinaryRequest) -> Never:
        _ = request
        self.calls += 1
        raise AssertionError("must not perform binary I/O")

    def execute_multipart(self, request: KnowledgeFSRemoteMultipartRequest) -> Never:
        _ = request
        self.calls += 1
        raise AssertionError("must not perform multipart I/O")

    def execute_sse(self, request: KnowledgeFSRemoteSSERequest) -> Never:
        _ = request
        self.calls += 1
        raise AssertionError("must not perform SSE I/O")


class PassThroughPayload:
    """Opaque payload for facade methods that forward their payload to the remote call untouched."""


@dataclass
class ValidatedResponse:
    """Stand-in for a patched ``model_validate`` result; the facade only reads its query images."""

    query_images: list[object] = field(default_factory=list)
    data: list[object] = field(default_factory=list)


class ServiceBroker(UnexpectedCapabilityIssuer):
    def __init__(self) -> None:
        self.service_calls: list[dict[str, object]] = []

    @override
    def issue_service(
        self,
        *,
        profile: KnowledgeFSServiceApiProfile,
        operation_id: str,
        resource_id: str | None = None,
        trace_id: str | None = None,
    ) -> KnowledgeFSIssuedProductCapability:
        self.service_calls.append(
            {"profile": profile, "operation_id": operation_id, "resource_id": resource_id, "trace_id": trace_id}
        )
        return KnowledgeFSIssuedProductCapability(
            token="service-capability",
            expires_at=datetime(2030, 1, 1, tzinfo=UTC),
            operation_id=operation_id,
            knowledge_space_id="space-1",
            knowledge_space_revision=9,
            trace_id="trace-1",
        )


def _offline_facade() -> KnowledgeFSDataFacade:
    """Facade whose broker and remote fail loudly; tests patch the delegation seam instead."""
    return KnowledgeFSDataFacade(broker=UnexpectedCapabilityIssuer(), remote=FailingRemote())


def _payload_dump(call: RecordedCall, *, exclude_none: bool = False) -> dict[str, object]:
    payload = call.kwargs["payload"]
    assert isinstance(payload, BaseModel)
    return payload.model_dump(mode="json", by_alias=True, exclude_none=exclude_none)


class RecordingBroker(UnexpectedCapabilityIssuer):
    def __init__(self) -> None:
        self.calls: list[dict[str, object]] = []

    @override
    def issue_interactive(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
        self.calls.append(kwargs)
        operation_id = kwargs["operation_id"]
        assert isinstance(operation_id, str)
        return KnowledgeFSIssuedProductCapability(
            token="capability-token",
            expires_at=datetime(2030, 1, 1, tzinfo=UTC),
            operation_id=operation_id,
            knowledge_space_id="space-1",
            knowledge_space_revision=9,
            trace_id="trace-1",
        )


class MutableClock:
    def __init__(self, current: datetime) -> None:
        self.current = current

    def __call__(self) -> datetime:
        return self.current

    def advance(self, *, seconds: int) -> None:
        self.current += timedelta(seconds=seconds)


class ExpiringRecordingBroker(UnexpectedCapabilityIssuer):
    def __init__(self, *, clock: MutableClock) -> None:
        self._clock = clock
        self.calls: list[dict[str, object]] = []

    @override
    def issue_interactive(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
        self.calls.append(kwargs)
        sequence = len(self.calls)
        return KnowledgeFSIssuedProductCapability(
            token=f"capability-token-{sequence}",
            expires_at=self._clock() + timedelta(seconds=60),
            operation_id=str(kwargs["operation_id"]),
            knowledge_space_id=f"space-{sequence}",
            knowledge_space_revision=sequence,
            trace_id=str(kwargs.get("trace_id") or "trace-1"),
        )


class RecordingRemote:
    def __init__(self) -> None:
        self.requests: list[KnowledgeFSRemoteJSONRequest] = []
        self.binary_requests: list[KnowledgeFSRemoteBinaryRequest] = []
        self.multipart_requests: list[KnowledgeFSRemoteMultipartRequest] = []
        self.sse_requests: list[KnowledgeFSRemoteSSERequest] = []

    def batch_space_summaries(self, **kwargs: object) -> dict[str, KnowledgeFSTechnicalSummary]:
        _ = kwargs
        return {}

    def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> dict[str, JsonValue]:
        self.requests.append(request)
        if request.operation_id in {"listKnowledgeFs", "findKnowledgeFs"}:
            return {"items": [], "path": "/knowledge", "truncated": False}
        if request.operation_id == "treeKnowledgeFs":
            return {
                "path": "/knowledge",
                "root": {
                    "kind": "directory",
                    "metadata": {},
                    "name": "knowledge",
                    "path": "/knowledge",
                },
                "truncated": False,
            }
        if request.operation_id == "grepKnowledgeFs":
            return {"matches": [], "path": "/knowledge", "truncated": False}
        if request.operation_id == "diffKnowledgeFs":
            return {
                "mode": "line",
                "newPath": "/knowledge/new.md",
                "oldPath": "/knowledge/old.md",
                "operations": [],
                "stats": {"delete": 0, "equal": 0, "insert": 0},
            }
        if request.operation_id == "catKnowledgeFs":
            return {
                "contentType": "text/markdown",
                "path": "/knowledge/readme.md",
                "text": "hello",
                "truncated": False,
            }
        if request.operation_id == "statKnowledgeFs":
            return {
                "metadata": {},
                "path": "/knowledge/readme.md",
                "resourceType": "document",
                "targetId": "document-1",
            }
        if request.operation_id in {"getSettings", "updateSettings"}:
            return {
                "activeProfileAvailable": False,
                "activeProfileRevisions": {},
                "capabilities": {
                    "deep": False,
                    "index": False,
                    "ingest": True,
                    "query": False,
                    "research": False,
                    "sourceSync": True,
                },
                "configurationState": "pending-validation",
                "embedding": {
                    "model": "embed-v1",
                    "pluginId": "plugin-1",
                    "provider": "provider-1",
                },
                "retrieval": None,
                "issues": [{"code": "missing", "field": "reasoning", "retryable": False}],
                "revision": 2,
            }
        if request.operation_id == "listMetadataFields":
            return {
                "items": [
                    {
                        "count": 2,
                        "createdAt": "2030-01-01T00:00:00Z",
                        "id": "field-1",
                        "name": "category",
                        "rowVersion": 3,
                        "type": "string",
                        "updatedAt": "2030-01-01T00:00:00Z",
                    }
                ],
                "nextCursor": None,
            }
        if request.operation_id in {
            "createMetadataField",
            "updateMetadataField",
        }:
            return {
                "count": 2,
                "createdAt": "2030-01-01T00:00:00Z",
                "id": "field-1",
                "name": "category",
                "rowVersion": 3,
                "type": "string",
                "updatedAt": "2030-01-01T00:00:00Z",
            }
        if request.operation_id == "deleteMetadataField":
            return {"deleted": True}
        if request.operation_id == "listSources":
            return {
                "items": [
                    {
                        "syncWorkflow": {
                            "canceledAt": None,
                            "checkpoint": "provider-read",
                            "completedAt": None,
                            "createdAt": "2030-01-01T00:00:00Z",
                            "cursor": None,
                            "executionAttempts": 1,
                            "id": "workflow-1",
                            "knowledgeSpaceId": "space-1",
                            "kind": "sync",
                            "lastErrorCode": None,
                            "maxExecutionAttempts": 3,
                            "progressCompleted": 2,
                            "progressFailed": 0,
                            "progressSkipped": 0,
                            "progressTotal": 5,
                            "sourceId": "source-1",
                            "state": "syncing",
                            "updatedAt": "2030-01-01T00:01:00Z",
                        },
                        "connectionId": None,
                        "createdAt": "2030-01-01T00:00:00Z",
                        "id": "source-1",
                        "knowledgeSpaceId": "space-1",
                        "lastSyncedAt": "2030-01-01T01:00:00Z",
                        "metadata": {},
                        "name": "Docs",
                        "permissionScope": [],
                        "status": "active",
                        "syncPolicy": {
                            "createdAt": "2030-01-01T00:00:00Z",
                            "enabled": True,
                            "expectedSourceVersion": 1,
                            "id": "policy-1",
                            "knowledgeSpaceId": "space-1",
                            "mode": "interval",
                            "revision": 1,
                            "sourceId": "source-1",
                            "updatedAt": "2030-01-01T00:00:00Z",
                        },
                        "type": "web",
                        "updatedAt": "2030-01-01T00:00:00Z",
                        "uri": "https://example.test/docs",
                        "version": 1,
                    }
                ],
                "nextCursor": None,
            }
        if request.operation_id in {"listResearchTasks", "listTraces"}:
            return {"items": [], "nextCursor": None}
        if request.operation_id == "createSource":
            return {
                "connectionId": None,
                "createdAt": "2030-01-01T00:00:00Z",
                "id": "source-1",
                "knowledgeSpaceId": "space-1",
                "metadata": {"team": "search"},
                "name": "Docs",
                "permissionScope": [],
                "status": "active",
                "type": "web",
                "updatedAt": "2030-01-01T00:00:00Z",
                "uri": "https://example.test/docs",
                "version": 1,
            }
        if request.operation_id in {"getSource", "updateSource"}:
            return {
                "connectionId": None,
                "createdAt": "2030-01-01T00:00:00Z",
                "id": "source-1",
                "knowledgeSpaceId": "space-1",
                "metadata": {},
                "name": "Docs",
                "permissionScope": [],
                "status": "active",
                "type": "web",
                "updatedAt": "2030-01-01T00:00:00Z",
                "uri": "https://example.test/docs",
                "version": 2,
            }
        if request.operation_id == "testSource":
            return {"valid": True}
        if request.operation_id == "getCompilationJob":
            return {
                "createdAt": 1.0,
                "documentAssetId": "document-1",
                "id": "job-1",
                "knowledgeSpaceId": "space-1",
                "stage": "queued",
                "tenantId": "tenant-1",
                "updatedAt": 1.0,
                "version": 1,
            }
        if request.operation_id == "getTrace":
            return {
                "createdAt": "2030-01-01T00:00:00Z",
                "id": "trace-1",
                "knowledgeSpaceId": "space-1",
                "mode": "fast",
                "query": "What changed?",
                "steps": [],
            }
        if request.operation_id == "listTraceEvidence":
            return {"items": [], "path": "/queries/trace-1/evidence", "truncated": False}
        if request.operation_id in {"deleteDocument", "deleteLogicalDocument", "deleteSource"}:
            return {
                "job": {
                    "checkpoint": "requested",
                    "createdAt": "2030-01-01T00:00:00Z",
                    "id": "00000000-0000-4000-8000-000000000001",
                    "knowledgeSpaceId": "space-1",
                    "runState": "queued",
                    "targetId": "00000000-0000-4000-8000-000000000002",
                    "targetType": (
                        "document"
                        if request.operation_id == "deleteDocument"
                        else "logical_document"
                        if request.operation_id == "deleteLogicalDocument"
                        else "source"
                    ),
                    "updatedAt": "2030-01-01T00:00:00Z",
                },
                "statusUrl": "/deletion-jobs/job-1",
            }
        if request.operation_id == "createResearchTask":
            return {
                "id": "research-1",
                "knowledgeSpaceId": "space-1",
                "query": "What changed?",
                "stage": "queued",
                "mode": "research",
                "topK": 5,
                "metadata": {},
                "cost": {"entries": [], "totalUsd": 0},
                "createdAt": 1.0,
                "updatedAt": 1.0,
            }
        if request.operation_id == "createUploadSession":
            return {
                "session": {
                    "expectedSizeBytes": 12,
                    "expiresAt": 2_060_000,
                    "id": "session-1",
                    "mode": "multipart",
                    "multipartPartCount": 1,
                    "multipartPartSizeBytes": 12,
                    "status": "ready",
                },
                "upload": None,
            }
        if request.operation_id == "presignUploadSessionPart":
            return {
                "expiresAt": 2_030_000,
                "headers": {"x-amz-checksum-sha256": "part-checksum"},
                "method": "PUT",
                "url": "https://storage.example/upload-part",
            }
        if request.operation_id in {"completeUploadSession", "abortUploadSession"}:
            return {
                "session": {
                    "expectedSizeBytes": 12,
                    "expiresAt": 2_060_000,
                    "id": "session-1",
                    "mode": "multipart",
                    "status": "completed" if request.operation_id == "completeUploadSession" else "aborted",
                }
            }
        return {"id": "space-1"}

    def execute_binary(self, request: KnowledgeFSRemoteBinaryRequest) -> dict[str, JsonValue]:
        self.binary_requests.append(request)
        return {
            "session": {
                "compilationJobId": "compilation-1",
                "completedAt": 2_000_000,
                "documentAssetId": "asset-1",
                "expectedSizeBytes": len(request.body),
                "expiresAt": 2_060_000,
                "id": "session-1",
                "mode": "small_fallback",
                "status": "completed",
            }
        }

    def execute_multipart(self, request: KnowledgeFSRemoteMultipartRequest) -> dict[str, JsonValue]:
        self.multipart_requests.append(request)
        return {
            "asset": {
                "createdAt": "2030-01-01T00:00:00Z",
                "filename": request.file.filename,
                "id": "asset-1",
                "knowledgeSpaceId": "space-1",
                "metadata": {},
                "mimeType": request.file.content_type,
                "objectKey": "documents/asset-1/upload.md",
                "parserStatus": "pending",
                "sha256": "sha256",
                "sizeBytes": len(request.file.body),
                "sourceId": None,
                "updatedAt": None,
                "version": 1,
            },
            "assetStatusUrl": "/knowledge-spaces/space-1/documents/asset-1",
            "compilationJob": {"id": "job-1", "stage": "queued"},
            "documentRevision": 1,
            "logicalDocument": {"id": "document-1", "revision": 1},
            "logicalDocumentId": "document-1",
            "statusUrl": "/knowledge-spaces/space-1/logical-documents/document-1/tasks/job-1",
        }

    def execute_sse(self, request: KnowledgeFSRemoteSSERequest) -> KnowledgeFSRemoteSSEResponse:
        self.sse_requests.append(request)
        return KnowledgeFSRemoteSSEResponse(
            status_code=200,
            headers=(("content-type", "text/event-stream"),),
            chunks=iter((b"data: ok\n\n",)),
            close=lambda: None,
        )


class ActiveSettingsRemote(RecordingRemote):
    def __init__(
        self,
        *,
        active_profile_available: bool | None = None,
        active_profile_revisions: dict[str, int] | None = None,
        configuration_state: str = "active",
        rerank_enabled: bool = True,
    ) -> None:
        super().__init__()
        self.active_profile_available = (
            configuration_state == "active" if active_profile_available is None else active_profile_available
        )
        self.active_profile_revisions = (
            {"embedding": 3, "retrieval": 4}
            if active_profile_revisions is None and self.active_profile_available
            else active_profile_revisions or {}
        )
        self.configuration_state = configuration_state
        self.rerank_enabled = rerank_enabled

    @override
    def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> dict[str, JsonValue]:
        if request.operation_id == "getSettings":
            self.requests.append(request)
            return {
                "activeProfileAvailable": self.active_profile_available,
                "activeProfileRevisions": dict[str, JsonValue](self.active_profile_revisions),
                "capabilities": {
                    "deep": self.active_profile_available,
                    "index": self.active_profile_available,
                    "ingest": self.active_profile_available or self.configuration_state == "pending-validation",
                    "query": self.active_profile_available,
                    "research": self.active_profile_available,
                    "sourceSync": self.active_profile_available or self.configuration_state == "pending-validation",
                },
                "configurationState": self.configuration_state,
                "embedding": {
                    "model": "embed-v1",
                    "pluginId": "plugin-1",
                    "provider": "provider-1",
                    **({"revision": 3} if self.configuration_state == "active" else {}),
                },
                "retrieval": {
                    "defaultMode": "fast",
                    "reasoningModel": {
                        "model": "reason-v1",
                        "pluginId": "plugin-1",
                        "provider": "provider-1",
                    },
                    "rerank": {
                        "enabled": self.rerank_enabled,
                        "model": (
                            {
                                "model": "rerank-v1",
                                "pluginId": "plugin-1",
                                "provider": "provider-1",
                            }
                            if self.rerank_enabled
                            else None
                        ),
                    },
                    **({"revision": 4} if self.configuration_state == "active" else {}),
                    "scoreThreshold": {
                        "enabled": False,
                        "stage": "rerank" if self.rerank_enabled else "mode-final",
                        "value": 0.5,
                    },
                    "topK": 3,
                },
                "issues": [],
                "revision": 9,
            }
        if request.operation_id in {"updateEmbeddingProfile", "updateRetrievalProfile"}:
            self.requests.append(request)
            return {
                "changedKind": "embedding" if request.operation_id == "updateEmbeddingProfile" else "retrieval",
                "checkpoint": "queued",
                "createdAt": "2026-07-28T00:00:00Z",
                "id": "migration-1",
                "knowledgeSpaceId": "space-1",
                "rebuildScope": "full-vector-space",
                "runState": "queued",
                "updatedAt": "2026-07-28T00:00:00Z",
            }
        if request.operation_id == "getProfileMigration":
            self.requests.append(request)
            return {
                "changedKind": "embedding",
                "checkpoint": "activated",
                "completedAt": "2026-07-28T00:01:00Z",
                "createdAt": "2026-07-28T00:00:00Z",
                "id": "migration-1",
                "knowledgeSpaceId": "space-1",
                "rebuildScope": "full-vector-space",
                "runState": "succeeded",
                "updatedAt": "2026-07-28T00:01:00Z",
            }
        return super().execute_json(request)


class QueryImageRemote(RecordingRemote):
    UPLOAD_FILE_ID = "00000000-0000-4000-8000-000000000001"

    @override
    def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> dict[str, JsonValue]:
        gateway_image: dict[str, JsonValue] = {
            "byteSize": 2048,
            "mimeType": "image/png",
            "sha256": "a" * 64,
            "uploadFileId": self.UPLOAD_FILE_ID,
        }
        if request.operation_id == "listTraces":
            self.requests.append(request)
            return {
                "items": [
                    {
                        "completed": True,
                        "createdAt": "2026-08-06T08:00:00.000Z",
                        "id": "trace-1",
                        "mode": "fast",
                        "profile": {},
                        "query": "What does this diagram show?",
                        "queryImages": [gateway_image],
                        "resultCount": 4,
                        "scores": {},
                        "stages": [],
                    },
                    {
                        "completed": True,
                        "createdAt": "2026-08-06T07:00:00.000Z",
                        "id": "trace-2",
                        "mode": "fast",
                        "profile": {},
                        "query": "text only",
                        "resultCount": 1,
                        "scores": {},
                        "stages": [],
                    },
                ]
            }
        if request.operation_id == "getTrace":
            self.requests.append(request)
            return {
                "createdAt": "2026-08-06T08:00:00.000Z",
                "id": "trace-1",
                "knowledgeSpaceId": "space-1",
                "mode": "fast",
                "query": "What does this diagram show?",
                "queryImages": [gateway_image],
                "steps": [],
            }
        if request.operation_id == "getResearchTask":
            self.requests.append(request)
            return {
                "cost": {},
                "createdAt": 1,
                "id": "task-1",
                "knowledgeSpaceId": "space-1",
                "metadata": {},
                "query": "",
                "queryImages": [{"uploadFileId": self.UPLOAD_FILE_ID}],
                "stage": "queued",
                "updatedAt": 1,
            }
        return super().execute_json(request)


def test_trace_and_research_history_carry_signed_query_image_previews() -> None:
    remote = QueryImageRemote()
    broker = RecordingBroker()
    preview_requests: list[tuple[str, str, list[str]]] = []

    def previews(
        *, tenant_id: str, account_id: str, upload_file_ids: Sequence[str]
    ) -> dict[str, KnowledgeFSQueryImagePreview]:
        preview_requests.append((tenant_id, account_id, list(upload_file_ids)))
        return {
            QueryImageRemote.UPLOAD_FILE_ID: KnowledgeFSQueryImagePreview(
                upload_file_id=QueryImageRemote.UPLOAD_FILE_ID,
                name="diagram.png",
                mime_type="image/png",
                byte_size=2048,
                preview_url="https://files.example.test/preview",
            )
        }

    facade = KnowledgeFSDataFacade(broker=broker, remote=remote, query_image_previews=previews)  # type: ignore[arg-type]
    common: _FacadeScope = {"tenant_id": "tenant-1", "account_id": "account-1", "control_space_id": "control-1"}

    traces = facade.list_traces(**common)
    trace = facade.get_trace(**common, trace_id="trace-1")
    task = facade.get_research_task(**common, task_id="task-1")

    assert [image.model_dump(mode="json") for image in traces.data[0].query_images] == [
        {
            "byte_size": 2048,
            "mime_type": "image/png",
            "name": "diagram.png",
            "preview_url": "https://files.example.test/preview",
            "upload_file_id": QueryImageRemote.UPLOAD_FILE_ID,
        }
    ]
    assert traces.data[1].query_images == []
    assert trace.query_images[0].preview_url == "https://files.example.test/preview"
    assert task.query_images[0].name == "diagram.png"
    assert task.query_images[0].byte_size == 2048
    # One batched lookup per response, scoped to the acting account.
    assert preview_requests == [
        ("tenant-1", "account-1", [QueryImageRemote.UPLOAD_FILE_ID]),
        ("tenant-1", "account-1", [QueryImageRemote.UPLOAD_FILE_ID]),
        ("tenant-1", "account-1", [QueryImageRemote.UPLOAD_FILE_ID]),
    ]


def test_knowledge_fs_commands_use_independent_manifest_operations_and_query_contracts() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]
    common: _FacadeScope = {
        "tenant_id": "tenant-1",
        "account_id": "account-1",
        "control_space_id": "control-1",
    }

    facade.list_knowledge_fs(
        **common,
        query=KnowledgeFSListQuery(
            path="/knowledge",
            limit=25,
            cursor="cursor-1",
            consistency_class="path-consistent",
        ),
    )
    facade.tree_knowledge_fs(
        **common,
        query=KnowledgeFSTreeQuery(path="/knowledge", limit=20, depth=3),
    )
    facade.grep_knowledge_fs(
        **common,
        query=KnowledgeFSGrepQuery(path="/knowledge", query="TODO", limit=10, timeout_ms=500),
    )
    facade.find_knowledge_fs(
        **common,
        query=KnowledgeFSFindQuery(
            path="/knowledge",
            limit=15,
            name_contains="readme",
            resource_type="document",
        ),
    )
    facade.diff_knowledge_fs(
        **common,
        query=KnowledgeFSDiffQuery(
            old_path="/knowledge/old.md",
            new_path="/knowledge/new.md",
            mode="line",
            semantic=True,
        ),
    )
    cat = facade.cat_knowledge_fs(
        **common,
        query=KnowledgeFSCatQuery(path="/knowledge/readme.md"),
    )
    facade.stat_knowledge_fs(
        **common,
        query=KnowledgeFSStatQuery(path="/knowledge/readme.md"),
    )

    assert [call["operation_id"] for call in broker.calls] == [
        "listKnowledgeFs",
        "treeKnowledgeFs",
        "grepKnowledgeFs",
        "findKnowledgeFs",
        "diffKnowledgeFs",
        "catKnowledgeFs",
        "statKnowledgeFs",
    ]
    assert [request.operation_id for request in remote.requests] == [
        "listKnowledgeFs",
        "treeKnowledgeFs",
        "grepKnowledgeFs",
        "findKnowledgeFs",
        "diffKnowledgeFs",
        "catKnowledgeFs",
        "statKnowledgeFs",
    ]
    assert remote.requests[0].query == (
        ("path", "/knowledge"),
        ("limit", "25"),
        ("cursor", "cursor-1"),
        ("consistencyClass", "path-consistent"),
    )
    assert ("q", "TODO") in remote.requests[2].query
    assert ("nameContains", "readme") in remote.requests[3].query
    assert ("semantic", "true") in remote.requests[4].query
    assert all(request.method == "GET" and request.payload is None for request in remote.requests)
    assert cat.text == "hello"


def test_facade_propagates_remote_io_failure() -> None:
    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=RecordingBroker(),
        remote=RecordingRemote(),
    )

    result = facade.get_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
    )

    assert result.revision == 2

    failing = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=RecordingBroker(),
        remote=FailingRemote(),
    )
    with pytest.raises(AssertionError, match="manifest gaps"):
        failing.get_settings(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
        )


def test_document_upload_authorizes_before_read_and_binds_bounded_multipart_request() -> None:
    observed: list[str] = []

    class RecordingAdmission:
        @contextmanager
        def admit(self, *, reserved_bytes: int) -> Generator[None]:
            assert broker.calls
            observed.append(f"admit:{reserved_bytes}")
            try:
                yield
            finally:
                observed.append("release")

    class OrderedRemote(RecordingRemote):
        @override
        def execute_multipart(self, request: KnowledgeFSRemoteMultipartRequest) -> dict[str, JsonValue]:
            observed.append("remote")
            return super().execute_multipart(request)

    remote = OrderedRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=broker,
        remote=remote,
        buffered_upload_admission=RecordingAdmission(),
    )

    def read_upload(max_bytes: int) -> KnowledgeFSRemoteMultipartFile:
        observed.append(f"read:{max_bytes}")
        assert broker.calls
        return KnowledgeFSRemoteMultipartFile(
            filename="upload.md",
            content_type="text/markdown",
            body=b"# Upload",
        )

    result = facade.create_document(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        body_reader=read_upload,
    )

    assert result.logical_document_id == "document-1"
    assert observed == ["admit:15728640", "read:15728640", "remote", "release"]
    assert broker.calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "createDocument",
        }
    ]
    assert remote.multipart_requests == [
        KnowledgeFSRemoteMultipartRequest(
            operation_id="createDocument",
            method="POST",
            path="/knowledge-spaces/space-1/documents",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            file=KnowledgeFSRemoteMultipartFile(
                filename="upload.md",
                content_type="text/markdown",
                body=b"# Upload",
            ),
        )
    ]


def test_document_upload_refreshes_capability_after_waiting_for_buffer_admission() -> None:
    clock = MutableClock(datetime(2030, 1, 1, tzinfo=UTC))
    broker = ExpiringRecordingBroker(clock=clock)
    remote = RecordingRemote()

    class DelayedAdmission:
        @contextmanager
        def admit(self, *, reserved_bytes: int) -> Generator[None]:
            assert reserved_bytes == 15 * 1024 * 1024
            assert len(broker.calls) == 1
            clock.advance(seconds=46)
            yield

    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=broker,
        remote=remote,
        buffered_upload_admission=DelayedAdmission(),
        clock=clock,
    )

    facade.create_document(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        body_reader=lambda _max_bytes: KnowledgeFSRemoteMultipartFile(
            filename="upload.md",
            content_type="text/markdown",
            body=b"# Upload",
        ),
    )

    assert broker.calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "createDocument",
        },
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "createDocument",
            "resource_id": None,
            "trace_id": "trace-1",
        },
    ]
    assert remote.multipart_requests[0].path == "/knowledge-spaces/space-2/documents"
    assert remote.multipart_requests[0].knowledge_space_id == "space-2"
    assert remote.multipart_requests[0].capability_token == "capability-token-2"


def test_legacy_buffered_query_fails_before_capability_or_remote_io() -> None:
    broker = FailingBroker()
    remote = FailingRemote()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    with pytest.raises(KnowledgeFSOperationUnavailableError, match="queries/admission"):
        facade.create_query(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSQueryCreatePayload(query="ignored"),
        )

    assert broker.calls == 0
    assert remote.calls == 0


def test_query_and_research_streams_use_the_internal_sse_transport() -> None:
    remote = RecordingRemote()
    facade = KnowledgeFSDataFacade(broker=RecordingBroker(), remote=remote)  # type: ignore[arg-type]

    query_response = facade.stream_query(
        capability_token="query-capability",
        trace_id="trace-1",
        payload=KnowledgeFSAdmittedQueryRequest(
            knowledgeSpaceId="space-1",
            query="What changed?",
            mode="fast",
        ),
    )
    research_response = facade.stream_research_task(
        capability_token="research-capability",
        trace_id="trace-2",
        task_id="task-1",
        knowledge_space_id="space-1",
        cursor="cursor-1",
        limit=25,
    )

    assert query_response.status_code == 200
    assert research_response.status_code == 200
    assert remote.sse_requests == [
        KnowledgeFSRemoteSSERequest(
            operation_id="createQuery",
            method="POST",
            path="/queries",
            capability_token="query-capability",
            trace_id="trace-1",
            payload={
                "activeDocumentIds": [],
                "activeEntityIds": [],
                "knowledgeSpaceId": "space-1",
                "mode": "fast",
                "query": "What changed?",
            },
        ),
        KnowledgeFSRemoteSSERequest(
            operation_id="streamResearchTask",
            method="GET",
            path="/research-tasks/task-1/events",
            capability_token="research-capability",
            trace_id="trace-2",
            payload=None,
            query=(
                ("knowledgeSpaceId", "space-1"),
                ("limit", "25"),
                ("cursor", "cursor-1"),
            ),
        ),
    ]


def test_upload_session_control_plane_uses_only_json_bff_calls_bound_to_the_space() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    created = facade.create_upload_session(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSUploadSessionCreatePayload(
            checksum_sha256_base64="whole-checksum",
            content_type="application/pdf",
            expected_size_bytes=12,
            file_name="guide.pdf",
        ),
        idempotency_key="upload-session-1",
    )
    presigned = facade.presign_upload_session_part(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        upload_session_id="session-1",
        part_number=1,
        payload=KnowledgeFSUploadPartPresignPayload(
            checksum_sha256_base64="part-checksum",
            content_length=12,
        ),
    )
    completed = facade.complete_upload_session(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        upload_session_id="session-1",
        payload=KnowledgeFSUploadSessionCompletePayload(
            parts=[
                KnowledgeFSUploadSessionPartPayload(
                    checksum_sha256_base64="part-checksum",
                    etag="etag-1",
                    part_number=1,
                )
            ]
        ),
    )
    aborted = facade.abort_upload_session(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        upload_session_id="session-1",
        payload=KnowledgeFSUploadSessionAbortPayload(),
    )

    assert created.session.status == "ready"
    assert presigned.url == "https://storage.example/upload-part"
    assert completed.session.status == "completed"
    assert aborted.session.status == "aborted"
    assert [call["operation_id"] for call in broker.calls] == [
        "createUploadSession",
        "presignUploadSessionPart",
        "completeUploadSession",
        "abortUploadSession",
    ]
    assert remote.requests == [
        KnowledgeFSRemoteJSONRequest(
            operation_id="createUploadSession",
            method="POST",
            path="/knowledge-spaces/space-1/upload-sessions",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            payload={
                "checksumSha256Base64": "whole-checksum",
                "contentType": "application/pdf",
                "expectedSizeBytes": 12,
                "fileName": "guide.pdf",
                "idempotencyKey": "upload-session-1",
            },
        ),
        KnowledgeFSRemoteJSONRequest(
            operation_id="presignUploadSessionPart",
            method="POST",
            path="/upload-sessions/session-1/parts/1/presign",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            payload={
                "checksumSha256Base64": "part-checksum",
                "contentLength": 12,
                "knowledgeSpaceId": "space-1",
            },
        ),
        KnowledgeFSRemoteJSONRequest(
            operation_id="completeUploadSession",
            method="POST",
            path="/upload-sessions/session-1/complete",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            payload={
                "parts": [
                    {
                        "checksumSha256Base64": "part-checksum",
                        "etag": "etag-1",
                        "partNumber": 1,
                    }
                ],
                "knowledgeSpaceId": "space-1",
            },
        ),
        KnowledgeFSRemoteJSONRequest(
            operation_id="abortUploadSession",
            method="POST",
            path="/upload-sessions/session-1/abort",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            payload={"knowledgeSpaceId": "space-1"},
        ),
    ]


def test_small_file_fallback_authorizes_before_read_and_binds_narrow_binary_request() -> None:
    observed: list[str] = []

    class RecordingAdmission:
        @contextmanager
        def admit(self, *, reserved_bytes: int) -> Generator[None]:
            observed.append(f"admit:{reserved_bytes}")
            try:
                yield
            finally:
                observed.append("release")

    class OrderedRemote(RecordingRemote):
        @override
        def execute_binary(self, request: KnowledgeFSRemoteBinaryRequest) -> dict[str, JsonValue]:
            observed.append("remote")
            return super().execute_binary(request)

    remote = OrderedRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=broker,
        remote=remote,
        buffered_upload_admission=RecordingAdmission(),
    )

    def read_body(max_bytes: int) -> bytes:
        assert broker.calls
        assert broker.calls[0]["operation_id"] == "uploadSmallFile"
        assert max_bytes == 15 * 1024 * 1024
        observed.append("read")
        return b"tiny"

    result = facade.upload_small_file(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        upload_session_id="session-1",
        body_reader=read_body,
    )

    assert result.session.status == "completed"
    assert observed == ["admit:15728640", "read", "remote", "release"]
    assert broker.calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "uploadSmallFile",
            "resource_id": "session-1",
        }
    ]
    assert remote.binary_requests == [
        KnowledgeFSRemoteBinaryRequest(
            operation_id="uploadSmallFile",
            method="POST",
            path="/upload-sessions/session-1/small-file",
            namespace_id="tenant-1",
            knowledge_space_id="space-1",
            capability_token="capability-token",
            trace_id="trace-1",
            body=b"tiny",
            query=(("knowledgeSpaceId", "space-1"),),
        )
    ]


def test_small_file_fallback_refreshes_capability_after_a_slow_body_read() -> None:
    clock = MutableClock(datetime(2030, 1, 1, tzinfo=UTC))
    broker = ExpiringRecordingBroker(clock=clock)
    remote = RecordingRemote()
    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=broker,
        remote=remote,
        clock=clock,
    )

    def read_body(max_bytes: int) -> bytes:
        assert max_bytes == 15 * 1024 * 1024
        assert len(broker.calls) == 1
        clock.advance(seconds=46)
        return b"tiny"

    facade.upload_small_file(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        upload_session_id="session-1",
        body_reader=read_body,
    )

    assert broker.calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "uploadSmallFile",
            "resource_id": "session-1",
        },
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "operation_id": "uploadSmallFile",
            "resource_id": "session-1",
            "trace_id": "trace-1",
        },
    ]
    assert remote.binary_requests[0].knowledge_space_id == "space-2"
    assert remote.binary_requests[0].capability_token == "capability-token-2"
    assert remote.binary_requests[0].query == (("knowledgeSpaceId", "space-2"),)


def test_small_file_fallback_denial_and_size_limit_stop_before_bytes_or_remote_io() -> None:
    class DenyingBroker(UnexpectedCapabilityIssuer):
        @override
        def issue_interactive(self, **kwargs: object) -> Never:
            _ = kwargs
            raise PermissionError("document write denied")

    denied_remote = FailingRemote()
    denied_facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=DenyingBroker(),
        remote=denied_remote,
    )
    reads = 0

    def forbidden_read(_: int) -> bytes:
        nonlocal reads
        reads += 1
        return b"must-not-read"

    with pytest.raises(PermissionError, match="document write denied"):
        denied_facade.upload_small_file(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            upload_session_id="session-1",
            body_reader=forbidden_read,
        )
    assert reads == 0
    assert denied_remote.calls == 0

    remote = RecordingRemote()
    facade = KnowledgeFSDataFacade(  # type: ignore[arg-type]
        broker=RecordingBroker(),
        remote=remote,
    )
    with pytest.raises(KnowledgeFSProductRequestRejectedError) as oversized:
        facade.upload_small_file(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            upload_session_id="session-1",
            body_reader=lambda maximum: b"x" * (maximum + 1),
        )
    assert oversized.value.status_code == 413
    assert remote.binary_requests == []


def test_json_facade_uses_kfs_camel_case_body_and_authoritative_revision() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    research = facade.create_research_task(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSResearchTaskCreatePayload(
            query="What changed?",
            mode="research",
            top_k=5,
        ),
    )
    facade.update_space(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSpaceUpdatePayload(name="Renamed", icon="grinning"),
    )

    assert research.knowledge_space_id == "space-1"
    assert research.stage == "queued"
    assert remote.requests[0].payload == {
        "knowledgeSpaceId": "space-1",
        "metadata": {},
        "mode": "research",
        "query": "What changed?",
        "topK": 5,
    }
    assert remote.requests[1].payload == {
        "expectedRevision": 9,
        "iconRef": "grinning",
        "name": "Renamed",
    }
    assert {call["control_space_id"] for call in broker.calls} == {"control-1"}


def test_basic_product_facade_resolves_control_space_then_uses_exact_kfs_routes() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    settings = facade.get_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
    )
    updated = facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            embedding=KnowledgeFSProfileModelSelection(
                model="embed-v1",
                plugin_id="plugin-1",
                provider="provider-1",
            ),
            expected_revision=1,
        ),
    )
    sources = facade.list_sources(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        cursor="source-cursor",
        limit=25,
    )
    source = facade.create_source(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSourceCreatePayload(
            metadata={"team": "search"},
            name="Docs",
            type="web",
            uri="https://example.test/docs",
        ),
    )
    tasks = facade.list_research_tasks(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        cursor="task-cursor",
    )
    traces = facade.list_traces(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        cursor="trace-cursor",
    )

    assert settings.revision == 2
    assert updated.settings.embedding is not None
    assert updated.settings.embedding.plugin_id == "plugin-1"
    assert len(sources.data) == 1
    assert sources.data[0].sync_workflow is not None
    assert sources.data[0].sync_workflow.id == "workflow-1"
    assert sources.data[0].sync_workflow.state == "syncing"
    assert sources.data[0].last_synced_at == datetime(2030, 1, 1, 1, tzinfo=UTC)
    assert sources.data[0].sync_policy is not None
    assert sources.data[0].sync_policy.mode == "interval"
    assert source.knowledge_space_id == "space-1"
    assert tasks.data == []
    assert traces.data == []
    assert [request.operation_id for request in remote.requests] == [
        "getSettings",
        "getSettings",
        "updateSettings",
        "listSources",
        "createSource",
        "listResearchTasks",
        "listTraces",
    ]
    assert [request.path for request in remote.requests] == [
        "/knowledge-spaces/space-1/product-settings",
        "/knowledge-spaces/space-1/product-settings",
        "/knowledge-spaces/space-1/product-settings",
        "/knowledge-spaces/space-1/sources",
        "/knowledge-spaces/space-1/sources",
        "/knowledge-spaces/space-1/research-tasks",
        "/knowledge-spaces/space-1/quality/traces",
    ]
    assert remote.requests[2].payload == {
        "embedding": {"model": "embed-v1", "pluginId": "plugin-1", "provider": "provider-1"},
        "expectedRevision": 1,
    }
    assert remote.requests[3].query == (("cursor", "source-cursor"), ("limit", "25"))
    assert remote.requests[4].payload == {
        "metadata": {"team": "search"},
        "name": "Docs",
        "permissionScope": [],
        "type": "web",
        "uri": "https://example.test/docs",
    }
    assert remote.requests[5].query == (("cursor", "task-cursor"),)
    assert remote.requests[6].query == (("cursor", "trace-cursor"),)
    assert {call["control_space_id"] for call in broker.calls} == {"control-1"}


def test_metadata_field_facade_uses_catalog_routes_and_row_version_cas() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    listed = facade.list_metadata_fields(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        cursor="field-cursor",
        limit=25,
    )
    facade.create_metadata_field(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSMetadataFieldCreatePayload(name="category", type="string"),
    )
    facade.update_metadata_field(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        field_id="field-1",
        payload=KnowledgeFSMetadataFieldUpdatePayload(expected_row_version=3, name="topic"),
    )
    deleted = facade.delete_metadata_field(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        field_id="field-1",
        expected_row_version=4,
    )

    assert listed.data[0].name == "category"
    assert deleted.deleted
    assert [request.operation_id for request in remote.requests] == [
        "listMetadataFields",
        "createMetadataField",
        "updateMetadataField",
        "deleteMetadataField",
    ]
    assert [request.path for request in remote.requests] == [
        "/knowledge-spaces/space-1/metadata-fields",
        "/knowledge-spaces/space-1/metadata-fields",
        "/knowledge-spaces/space-1/metadata-fields/field-1",
        "/knowledge-spaces/space-1/metadata-fields/field-1",
    ]
    assert remote.requests[0].query == (("cursor", "field-cursor"), ("limit", "25"))
    assert remote.requests[1].payload == {"name": "category", "type": "string"}
    assert remote.requests[2].payload == {"expectedRowVersion": 3, "name": "topic"}
    assert remote.requests[3].query == (("expectedRowVersion", "4"),)
    assert {call["control_space_id"] for call in broker.calls} == {"control-1"}


def test_active_settings_revision_conflict_is_actionable_without_remote_mutation() -> None:
    remote = ActiveSettingsRemote()
    facade = KnowledgeFSDataFacade(broker=RecordingBroker(), remote=remote)  # type: ignore[arg-type]
    with pytest.raises(KnowledgeFSProductRequestRejectedError) as error:
        facade.update_settings(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSSettingsPayload(
                expected_revision=8,
                embedding=KnowledgeFSProfileModelSelection(
                    model="embed-v2", plugin_id="plugin-2", provider="provider-2"
                ),
            ),
        )
    assert error.value.status_code == 409
    assert error.value.failure is not None
    assert error.value.failure.code == "KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT"
    assert "Reload" in error.value.failure.message
    assert [request.operation_id for request in remote.requests] == ["getSettings"]


def test_active_settings_use_durable_profile_migration_routes() -> None:
    embedding_remote = ActiveSettingsRemote()
    embedding_facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=embedding_remote,
    )  # type: ignore[arg-type]

    embedding_result = embedding_facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            embedding=KnowledgeFSProfileModelSelection(
                model="embed-v2",
                plugin_id="plugin-2",
                provider="provider-2",
            ),
            expected_revision=9,
        ),
    )

    assert embedding_result.settings.configuration_state == "active"
    assert embedding_result.migration is not None
    assert embedding_result.migration.run_state == "queued"
    assert [request.operation_id for request in embedding_remote.requests] == [
        "getSettings",
        "updateEmbeddingProfile",
    ]
    assert embedding_remote.requests[1].path == "/knowledge-spaces/space-1/embedding-profile"
    assert embedding_remote.requests[1].payload == {
        "model": "embed-v2",
        "pluginId": "plugin-2",
        "provider": "provider-2",
    }

    retrieval_remote = ActiveSettingsRemote()
    retrieval_facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=retrieval_remote,
    )  # type: ignore[arg-type]
    retrieval_profile = KnowledgeFSProductRetrievalProfile(
        default_mode="research",
        reasoning_model=KnowledgeFSProfileModelSelection(
            model="reason-v2",
            plugin_id="plugin-2",
            provider="provider-2",
        ),
        rerank=KnowledgeFSProductRerankProfile(
            enabled=True,
            model=KnowledgeFSProfileModelSelection(
                model="rerank-v2",
                plugin_id="plugin-2",
                provider="provider-2",
            ),
        ),
        score_threshold=KnowledgeFSProductScoreThreshold(
            enabled=True,
            stage="mode-final",
            value=0.6,
        ),
        top_k=6,
    )

    retrieval_facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            expected_revision=9,
            retrieval=retrieval_profile,
        ),
    )

    assert [request.operation_id for request in retrieval_remote.requests] == [
        "getSettings",
        "updateRetrievalProfile",
    ]
    assert retrieval_remote.requests[1].path == "/knowledge-spaces/space-1/retrieval-profile"
    assert retrieval_remote.requests[1].payload == {
        "expectedRevision": 4,
        "profile": {
            "defaultMode": "research",
            "reasoningModel": {
                "model": "reason-v2",
                "pluginId": "plugin-2",
                "provider": "provider-2",
            },
            "rerank": {
                "enabled": True,
                "model": {
                    "model": "rerank-v2",
                    "pluginId": "plugin-2",
                    "provider": "provider-2",
                },
            },
            "scoreThreshold": {
                "enabled": True,
                "stage": "mode-final",
                "value": 0.6,
            },
            "topK": 6,
        },
    }


def test_active_settings_accept_direct_unpublished_profile_activation() -> None:
    class DirectActivationRemote(ActiveSettingsRemote):
        @override
        def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> dict[str, JsonValue]:
            if request.operation_id == "updateRetrievalProfile":
                self.requests.append(request)
                return {
                    "defaultMode": "fast",
                    "reasoningModel": {
                        "model": "reason-v1",
                        "pluginId": "plugin-1",
                        "provider": "provider-1",
                    },
                    "rerank": {
                        "enabled": True,
                        "model": {
                            "model": "rerank-v1",
                            "pluginId": "plugin-1",
                            "provider": "provider-1",
                        },
                    },
                    "revision": 5,
                    "scoreThreshold": {"enabled": True, "stage": "rerank", "value": 0.51},
                    "topK": 3,
                }
            return super().execute_json(request)

    remote = DirectActivationRemote()
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    result = facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            expected_revision=9,
            retrieval=KnowledgeFSProductRetrievalProfile(
                default_mode="fast",
                reasoning_model=KnowledgeFSProfileModelSelection(
                    model="reason-v1",
                    plugin_id="plugin-1",
                    provider="provider-1",
                ),
                rerank=KnowledgeFSProductRerankProfile(
                    enabled=True,
                    model=KnowledgeFSProfileModelSelection(
                        model="rerank-v1",
                        plugin_id="plugin-1",
                        provider="provider-1",
                    ),
                ),
                score_threshold=KnowledgeFSProductScoreThreshold(
                    enabled=True,
                    stage="rerank",
                    value=0.51,
                ),
                top_k=3,
            ),
        ),
    )

    assert result.migration is None
    assert [request.operation_id for request in remote.requests] == [
        "getSettings",
        "updateRetrievalProfile",
        "getSettings",
    ]


def test_setup_required_settings_without_active_profile_use_product_settings_route() -> None:
    remote = ActiveSettingsRemote(
        active_profile_available=False,
        configuration_state="setup-required",
        rerank_enabled=False,
    )
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    result = facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            expected_revision=9,
            retrieval=KnowledgeFSProductRetrievalProfile(
                default_mode="fast",
                reasoning_model=KnowledgeFSProfileModelSelection(
                    model="reason-v1",
                    plugin_id="plugin-1",
                    provider="provider-1",
                ),
                rerank=KnowledgeFSProductRerankProfile(
                    enabled=True,
                    model=KnowledgeFSProfileModelSelection(
                        model="rerank-v1",
                        plugin_id="plugin-1",
                        provider="provider-1",
                    ),
                ),
                score_threshold=KnowledgeFSProductScoreThreshold(
                    enabled=False,
                    stage="rerank",
                    value=0.5,
                ),
                top_k=3,
            ),
        ),
    )

    assert result.settings.configuration_state == "pending-validation"
    assert result.migration is None
    assert [request.operation_id for request in remote.requests] == [
        "getSettings",
        "updateSettings",
    ]
    assert remote.requests[1].payload == {
        "expectedRevision": 9,
        "retrieval": {
            "defaultMode": "fast",
            "reasoningModel": {
                "model": "reason-v1",
                "pluginId": "plugin-1",
                "provider": "provider-1",
            },
            "rerank": {
                "enabled": True,
                "model": {
                    "model": "rerank-v1",
                    "pluginId": "plugin-1",
                    "provider": "provider-1",
                },
            },
            "scoreThreshold": {"enabled": False, "stage": "rerank", "value": 0.5},
            "topK": 3,
        },
    }


def test_setup_required_settings_with_existing_profiles_use_migration_route() -> None:
    remote = ActiveSettingsRemote(
        active_profile_available=False,
        active_profile_revisions={"embedding": 1, "retrieval": 1},
        configuration_state="setup-required",
        rerank_enabled=False,
    )
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    result = facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            expected_revision=9,
            retrieval=KnowledgeFSProductRetrievalProfile(
                default_mode="fast",
                reasoning_model=KnowledgeFSProfileModelSelection(
                    model="reason-v1",
                    plugin_id="plugin-1",
                    provider="provider-1",
                ),
                rerank=KnowledgeFSProductRerankProfile(
                    enabled=True,
                    model=KnowledgeFSProfileModelSelection(
                        model="rerank-v1",
                        plugin_id="plugin-1",
                        provider="provider-1",
                    ),
                ),
                score_threshold=KnowledgeFSProductScoreThreshold(
                    enabled=False,
                    stage="rerank",
                    value=0.5,
                ),
                top_k=3,
            ),
        ),
    )

    assert result.migration is not None
    assert [request.operation_id for request in remote.requests] == [
        "getSettings",
        "updateRetrievalProfile",
    ]
    payload = remote.requests[1].payload
    assert isinstance(payload, dict)
    assert payload["expectedRevision"] == 1


def test_failed_candidate_with_active_profiles_uses_the_migration_route() -> None:
    remote = ActiveSettingsRemote(
        active_profile_available=True,
        configuration_state="validation-failed",
    )
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    result = facade.update_settings(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        payload=KnowledgeFSSettingsPayload(
            embedding=KnowledgeFSProfileModelSelection(
                model="embed-v2",
                plugin_id="plugin-2",
                provider="provider-2",
            ),
            expected_revision=9,
        ),
    )

    assert result.settings.active_profile_available is True
    assert result.settings.embedding is not None
    assert result.settings.embedding.revision is None
    assert result.migration is not None
    assert [request.operation_id for request in remote.requests] == [
        "getSettings",
        "updateEmbeddingProfile",
    ]


def test_get_profile_migration_uses_the_durable_migration_route() -> None:
    remote = ActiveSettingsRemote()
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    result = facade.get_profile_migration(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        migration_id="migration-1",
    )

    assert result.run_state == "succeeded"
    assert remote.requests[0].path == ("/knowledge-spaces/space-1/profile-migrations/migration-1")


def test_active_settings_reject_concurrent_profile_migrations() -> None:
    remote = ActiveSettingsRemote()
    facade = KnowledgeFSDataFacade(
        broker=RecordingBroker(),
        remote=remote,
    )  # type: ignore[arg-type]

    with pytest.raises(KnowledgeFSProductRequestRejectedError) as error:
        facade.update_settings(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSSettingsPayload(
                embedding=KnowledgeFSProfileModelSelection(
                    model="embed-v2",
                    plugin_id="plugin-2",
                    provider="provider-2",
                ),
                expected_revision=9,
                retrieval=KnowledgeFSProductRetrievalProfile(
                    default_mode="fast",
                    reasoning_model=KnowledgeFSProfileModelSelection(
                        model="reason-v2",
                        plugin_id="plugin-2",
                        provider="provider-2",
                    ),
                    rerank=KnowledgeFSProductRerankProfile(
                        enabled=True,
                        model=KnowledgeFSProfileModelSelection(
                            model="rerank-v2",
                            plugin_id="plugin-2",
                            provider="provider-2",
                        ),
                    ),
                    score_threshold=KnowledgeFSProductScoreThreshold(
                        enabled=False,
                        stage="rerank",
                        value=0.5,
                    ),
                    top_k=3,
                ),
            ),
        )

    assert error.value.status_code == 422
    assert [request.operation_id for request in remote.requests] == ["getSettings"]


def test_golden_question_facade_binds_direct_evidence_metadata() -> None:
    facade = _offline_facade()
    raw = {
        "createdAt": "2026-08-02T12:00:00Z",
        "expectedEvidenceIds": ["node-1"],
        "id": "golden-1",
        "metadata": {
            "annotation": "Reviewer note",
            "evidenceText": "Refunds are available for 30 days.",
            "matchPolicy": "all",
        },
        "question": "How long is the refund window?",
        "tags": ["billing"],
        "updatedAt": "2026-08-02T12:00:00Z",
    }
    interactive = CallRecorder(result=raw)

    with patch.object(facade, "_interactive", interactive):
        result = facade.create_golden_question(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSGoldenQuestionPayload(
                annotation=" Reviewer note ",
                evidence_text=" Refunds are available for 30 days. ",
                expected_evidence_ids=[" node-1 ", "node-1"],
                question=" How long is the refund window? ",
                tags=[" billing ", "billing"],
            ),
        )

    assert result.status == "active"
    assert result.expected_evidence_ids == ["node-1"]
    assert interactive.last.kwargs["operation_id"] == "createGoldenQuestion"
    assert _payload_dump(interactive.last) == {
        "expectedEvidenceIds": ["node-1"],
        "metadata": {
            "annotation": "Reviewer note",
            "evidenceText": "Refunds are available for 30 days.",
            "matchPolicy": "all",
        },
        "question": "How long is the refund window?",
        "tags": ["billing"],
    }


def test_golden_question_update_preserves_evidence_when_new_fields_are_omitted() -> None:
    facade = _offline_facade()
    interactive_child = CallRecorder(
        result={
            "createdAt": "2026-08-02T12:00:00Z",
            "expectedEvidenceIds": ["node-1"],
            "id": "golden-1",
            "metadata": {
                "annotation": "Updated note",
                "evidenceText": "Existing evidence",
                "lifecycleStatus": "active",
                "matchPolicy": "any",
            },
            "question": "Updated question?",
            "tags": [],
            "updatedAt": "2026-08-02T12:01:00Z",
        }
    )

    with patch.object(facade, "_interactive_child", interactive_child):
        result = facade.update_golden_question(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            question_id="golden-1",
            payload=KnowledgeFSGoldenQuestionPayload(
                annotation="Updated note",
                question="Updated question?",
            ),
        )

    assert result.expected_evidence_ids == ["node-1"]
    assert result.match_policy == "any"
    assert _payload_dump(interactive_child.last, exclude_none=True) == {
        "metadata": {"annotation": "Updated note"},
        "question": "Updated question?",
        "tags": [],
    }


def test_golden_question_facade_matches_evidence_and_forwards_csv_as_one_batch() -> None:
    facade = _offline_facade()
    interactive = CallRecorder(
        outcomes=deque(
            [
                {
                    "items": [
                        {
                            "candidates": [
                                {
                                    "documentAssetId": "document-1",
                                    "nodeId": "node-1",
                                    "projectionId": "projection-1",
                                    "score": 0.91,
                                    "sectionPath": ["Refunds"],
                                    "text": "Refunds are available for 30 days.",
                                }
                            ],
                            "evidenceText": "Refund policy",
                            "matched": True,
                        }
                    ]
                },
                {
                    "activeCount": 1,
                    "draftCount": 0,
                    "items": [
                        {
                            "expectedEvidenceId": "node-1",
                            "questionId": "golden-1",
                            "rowIndex": 0,
                            "similarity": 0.91,
                            "status": "active",
                        }
                    ],
                },
            ]
        )
    )

    with patch.object(facade, "_interactive", interactive):
        match = facade.match_golden_question_evidence(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSGoldenQuestionEvidenceMatchPayload(evidence=" Refund policy "),
        )
        imported = facade.bulk_import_golden_questions(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSGoldenQuestionBulkImportPayload(
                rows=[
                    KnowledgeFSGoldenQuestionBulkImportRowPayload(
                        evidence=" Refunds are available for 30 days. ",
                        question=" How long is the refund window? ",
                        tags=[" billing ", "billing"],
                    )
                ]
            ),
        )

    assert match.matched is True
    assert match.candidates[0].node_id == "node-1"
    assert imported.active_count == 1
    assert imported.items[0].question_id == "golden-1"
    assert [call.kwargs["operation_id"] for call in interactive.calls] == [
        "matchGoldenQuestionEvidence",
        "bulkImportGoldenQuestions",
    ]
    assert _payload_dump(interactive.calls[0], exclude_none=True) == {
        "evidenceTexts": ["Refund policy"],
        "minimumSimilarity": 0.7,
        "topK": 5,
    }
    assert _payload_dump(interactive.calls[1]) == {
        "matchPolicy": "all",
        "minimumSimilarity": 0.7,
        "rows": [
            {
                "evidence": "Refunds are available for 30 days.",
                "metadata": {
                    "evidenceText": "Refunds are available for 30 days.",
                    "importSource": "csv",
                },
                "question": "How long is the refund window?",
                "tags": ["billing"],
            }
        ],
    }


def test_golden_question_facade_resolves_saved_evidence_ids_without_a_search_term() -> None:
    facade = _offline_facade()
    interactive = CallRecorder(
        result={
            "items": [],
            "resolvedEvidence": [
                {
                    "documentAssetId": "document-1",
                    "nodeId": "node-1",
                    "pageNumber": 2,
                    "sectionPath": ["Permissions", "Roles"],
                    "text": "Only workspace owners can change permissions.",
                }
            ],
        }
    )

    with patch.object(facade, "_interactive", interactive):
        result = facade.match_golden_question_evidence(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSGoldenQuestionEvidenceMatchPayload(node_ids=[" node-1 ", "node-1"]),
        )

    assert result.evidence == ""
    assert result.matched is False
    assert result.candidates[0].node_id == "node-1"
    assert result.candidates[0].projection_id is None
    assert result.candidates[0].score is None
    assert _payload_dump(interactive.last, exclude_none=True) == {
        "minimumSimilarity": 0.7,
        "nodeIds": ["node-1"],
        "topK": 5,
    }


@pytest.mark.parametrize(
    "remote_response",
    [None, True, 1, 1.5, [], "invalid", {}, {"items": []}, {"items": [None]}],
)
def test_golden_question_evidence_match_rejects_malformed_remote_response(remote_response: object) -> None:
    facade = _offline_facade()

    with (
        patch.object(facade, "_interactive", return_value=remote_response),
        pytest.raises(KnowledgeFSProductRemoteError, match="invalid evidence match response"),
    ):
        facade.match_golden_question_evidence(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            payload=KnowledgeFSGoldenQuestionEvidenceMatchPayload(evidence="Refund policy"),
        )


def test_settings_dto_rejects_fast_threshold_without_rerank() -> None:
    with pytest.raises(ValueError, match="requires rerank"):
        KnowledgeFSProductRetrievalProfile(
            default_mode="fast",
            reasoning_model=KnowledgeFSProfileModelSelection(
                model="reason-v1",
                plugin_id="plugin-1",
                provider="provider-1",
            ),
            rerank=KnowledgeFSProductRerankProfile(enabled=False),
            score_threshold=KnowledgeFSProductScoreThreshold(
                enabled=True,
                stage="mode-final",
                value=0.5,
            ),
            top_k=3,
        )


def test_advanced_facade_binds_child_resources_parent_space_and_idempotency() -> None:
    remote = RecordingRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]

    source = facade.update_source(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        source_id="source-1",
        payload=KnowledgeFSSourceUpdatePayload(
            name="Docs",
            providerParameters={"limit": 50, "url": "https://docs.example.com"},
            uri="https://docs.example.com",
        ),
    )
    credential_test = facade.test_source(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        source_id="source-1",
    )
    job = facade.get_compilation_job(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        job_id="job-1",
    )
    trace = facade.get_trace(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        trace_id="trace-1",
    )
    evidence = facade.list_trace_entries(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        trace_id="trace-1",
        kind="evidence",
        limit=25,
    )
    deletion = facade.delete_document(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        document_id="document-1",
        payload=KnowledgeFSDocumentDeletePayload(expected_revision=2),
        idempotency_key="delete-document-once",
    )

    assert source.version == 2
    assert remote.requests[-6].payload == {
        "name": "Docs",
        "providerParameters": {"limit": 50, "url": "https://docs.example.com"},
        "uri": "https://docs.example.com",
    }
    assert credential_test.valid is True
    assert job.id == "job-1"
    assert trace.id == "trace-1"
    assert evidence.data == []
    assert deletion.job.target_type == "document"
    assert [request.path for request in remote.requests[-6:]] == [
        "/knowledge-spaces/space-1/sources/source-1",
        "/knowledge-spaces/space-1/sources/source-1/test",
        "/jobs/job-1",
        "/queries/trace-1",
        "/queries/trace-1/evidence",
        "/knowledge-spaces/space-1/documents/document-1",
    ]
    assert remote.requests[-4].query == (("knowledgeSpaceId", "space-1"),)
    assert remote.requests[-3].query == (("knowledgeSpaceId", "space-1"),)
    assert remote.requests[-2].query == (("limit", "25"), ("knowledgeSpaceId", "space-1"))
    assert remote.requests[-1].headers == (("Idempotency-Key", "delete-document-once"),)
    assert [call["resource_id"] for call in broker.calls[-6:]] == [
        "source-1",
        "source-1",
        "job-1",
        "trace-1",
        "trace-1",
        "document-1",
    ]


def test_deletion_receipt_read_is_scoped_to_the_admitted_knowledge_space() -> None:
    class DeletionReceiptRemote(RecordingRemote):
        @override
        def execute_json(self, request: KnowledgeFSRemoteJSONRequest) -> dict[str, JsonValue]:
            self.requests.append(request)
            return {
                "id": "deletion-1",
                "knowledgeSpaceId": "space-1",
                "targetType": "logical_document",
                "targetId": "logical-1",
                "checkpoint": "completed",
                "runState": "completed",
                "createdAt": "2030-01-01T00:00:00Z",
                "updatedAt": "2030-01-01T00:00:01Z",
            }

    remote = DeletionReceiptRemote()
    broker = RecordingBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)  # type: ignore[arg-type]
    receipt = facade.get_deletion_job(
        tenant_id="tenant-1", account_id="account-1", control_space_id="control-1", job_id="deletion-1"
    )
    assert receipt.target_id == "logical-1"
    assert receipt.run_state == "completed"
    request = remote.requests[-1]
    assert request.path == "/deletion-jobs/deletion-1"
    assert request.query == (("knowledgeSpaceId", "space-1"),)
    assert request.namespace_id == "tenant-1"
    assert broker.calls[-1]["resource_id"] == "deletion-1"
    assert broker.calls[-1]["control_space_id"] == "control-1"


def test_logical_document_delete_preserves_initial_row_version() -> None:
    remote = RecordingRemote()
    facade = KnowledgeFSDataFacade(broker=RecordingBroker(), remote=remote)  # type: ignore[arg-type]

    deletion = facade.delete_logical_document(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        document_id="document-1",
        payload=KnowledgeFSLogicalDocumentDeletePayload(expected_revision=0),
        idempotency_key="delete-logical-once",
    )

    request = remote.requests[-1]
    assert deletion.job.target_type == "logical_document"
    assert request.operation_id == "deleteLogicalDocument"
    assert request.path == "/knowledge-spaces/space-1/logical-documents/document-1"
    assert request.payload == {"expectedRevision": 0}
    assert request.headers == (("Idempotency-Key", "delete-logical-once"),)


@pytest.mark.parametrize(
    (
        "method_name",
        "response_name",
        "operation_id",
        "specific_kwargs",
        "child_resource_id",
    ),
    [
        (
            KnowledgeFSDataFacade.get_overview_stats,
            data_facade_module.KnowledgeFSOverviewBaseStatsResponse,
            "getOverviewStats",
            {},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_overview_query_outcomes,
            data_facade_module.KnowledgeFSOverviewQueryOutcomesResponse,
            "getOverviewQueryOutcomes",
            {"window": "7d"},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_overview_inventory,
            data_facade_module.KnowledgeFSOverviewInventoryResponse,
            "getOverviewInventory",
            {},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_overview_attention,
            data_facade_module.KnowledgeFSOverviewAttentionListResponse,
            "listOverviewAttention",
            {"include_dismissed": False, "limit": 20},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_overview_activity,
            data_facade_module.KnowledgeFSOverviewActivityListResponse,
            "listOverviewActivity",
            {
                "action": None,
                "actor_id": None,
                "actor_type": None,
                "cursor": "cursor-1",
                "from_at": "2026-07-01T00:00:00Z",
                "limit": 20,
                "resource_type": None,
                "result": None,
                "to_at": None,
            },
            None,
        ),
        (
            KnowledgeFSDataFacade.get_overview_health,
            data_facade_module.KnowledgeFSOverviewHealthResponse,
            "getOverviewHealth",
            {},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_documents,
            data_facade_module.KnowledgeFSDocumentListResponse,
            "listDocuments",
            {"cursor": "cursor-1"},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_logical_documents,
            data_facade_module.KnowledgeFSLogicalDocumentListResponse,
            "listLogicalDocuments",
            {"cursor": "cursor-1", "limit": 25, "query": "late report", "status": "processing"},
            None,
        ),
        (
            KnowledgeFSDataFacade.resolve_document_reference,
            data_facade_module.KnowledgeFSResolvedDocumentReferenceResponse,
            "resolveDocumentReference",
            {"document_asset_id": "asset-1", "document_asset_version": 7},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_logical_document,
            data_facade_module.KnowledgeFSLogicalDocumentResponse,
            "getLogicalDocument",
            {"document_id": "document-1"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.delete_logical_document,
            data_facade_module.KnowledgeFSDurableDeletionAcceptedResponse,
            "deleteLogicalDocument",
            {
                "document_id": "document-1",
                "payload": PassThroughPayload(),
                "idempotency_key": "delete-logical-document-once",
            },
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.get_document,
            data_facade_module.KnowledgeFSDocumentResponse,
            "getDocument",
            {"document_id": "document-1"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.get_document_outline,
            data_facade_module.KnowledgeFSDocumentOutlineResponse,
            "getDocumentOutline",
            {"document_id": "document-1"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.get_document_multimodal_manifest,
            data_facade_module.KnowledgeFSDocumentMultimodalManifest,
            "getDocumentMultimodalManifest",
            {"document_id": "document-1"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.list_document_revisions,
            data_facade_module.KnowledgeFSDocumentRevisionListResponse,
            "listDocumentRevisions",
            {"document_id": "document-1", "cursor": "cursor-1", "limit": 1},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.update_document_metadata,
            data_facade_module.KnowledgeFSLogicalDocumentResponse,
            "updateDocumentMetadata",
            {"document_id": "document-1", "payload": PassThroughPayload()},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.list_document_chunks,
            data_facade_module.KnowledgeFSDocumentChunkListResponse,
            "listDocumentChunks",
            {"document_id": "document-1", "revision": 2, "cursor": "cursor-1", "query_text": "risk"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.get_document_chunk,
            data_facade_module.KnowledgeFSDocumentChunkResponse,
            "getDocumentChunk",
            {"document_id": "document-1", "revision": 2, "chunk_id": "chunk-1"},
            "document-1",
        ),
        (
            KnowledgeFSDataFacade.bulk_delete_documents,
            data_facade_module.KnowledgeFSBulkDeletionAcceptedResponse,
            "bulkDeleteDocuments",
            {"payload": PassThroughPayload(), "idempotency_key": "bulk-delete-once"},
            None,
        ),
        (
            KnowledgeFSDataFacade.reindex_documents,
            data_facade_module.KnowledgeFSDocumentReindexResponse,
            "reindexDocuments",
            {"payload": PassThroughPayload()},
            None,
        ),
        (
            KnowledgeFSDataFacade.cancel_compilation_job,
            data_facade_module.KnowledgeFSDocumentCompilationJobResponse,
            "cancelCompilationJob",
            {"job_id": "job-1"},
            "job-1",
        ),
        (
            KnowledgeFSDataFacade.retry_compilation_job,
            data_facade_module.KnowledgeFSDocumentCompilationJobResponse,
            "retryCompilationJob",
            {"job_id": "job-1"},
            "job-1",
        ),
        (
            KnowledgeFSDataFacade.get_bulk_job,
            data_facade_module.KnowledgeFSBulkJobResponse,
            "getBulkJob",
            {"job_id": "job-1"},
            "job-1",
        ),
        (
            KnowledgeFSDataFacade.list_background_tasks,
            data_facade_module.KnowledgeFSBackgroundTaskListResponse,
            "listBackgroundTasks",
            {"cursor": "cursor-1", "limit": 25},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_background_tasks,
            data_facade_module.KnowledgeFSBackgroundTaskListResponse,
            "listBackgroundTasks",
            {"limit": 25, "task_ids": "018f0d60-7a49-7cc2-9c1b-5b36f18f2c42"},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_golden_questions,
            data_facade_module.KnowledgeFSGoldenQuestionListResponse,
            "listGoldenQuestions",
            {"cursor": "cursor-1", "limit": 25},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_bad_cases,
            data_facade_module.KnowledgeFSBadCaseListResponse,
            "listQualityBadCases",
            {"cursor": "cursor-1", "limit": 25},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_bad_case,
            data_facade_module.KnowledgeFSBadCaseResponse,
            "getQualityBadCase",
            {"bad_case_id": "bad-case-1"},
            "bad-case-1",
        ),
        (
            KnowledgeFSDataFacade.create_quality_replay,
            data_facade_module.KnowledgeFSQualityReplayResponse,
            "createQualityReplay",
            {"payload": PassThroughPayload(), "idempotency_key": "quality-replay-once"},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_quality_replays,
            data_facade_module.KnowledgeFSQualityReplayListResponse,
            "listQualityReplays",
            {"cursor": "cursor-1", "limit": 25, "mode": "deep", "state": "passed"},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_quality_replay,
            data_facade_module.KnowledgeFSQualityReplayResponse,
            "getQualityReplay",
            {"run_id": "replay-run-1", "evidence_item_id": "replay-item-1"},
            "replay-run-1",
        ),
        (
            KnowledgeFSDataFacade.cancel_background_task,
            data_facade_module.KnowledgeFSBackgroundTaskResponse,
            "cancelBackgroundTask",
            {"task_kind": "source", "task_id": "task-1"},
            "task-1",
        ),
        (
            KnowledgeFSDataFacade.retry_background_task,
            data_facade_module.KnowledgeFSBackgroundTaskResponse,
            "retryBackgroundTask",
            {"task_kind": "document_bulk", "task_id": "task-1"},
            "task-1",
        ),
        (
            KnowledgeFSDataFacade.get_source,
            data_facade_module.KnowledgeFSSourceResponse,
            "getSource",
            {"source_id": "source-1"},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.delete_source,
            data_facade_module.KnowledgeFSDurableDeletionAcceptedResponse,
            "deleteSource",
            {
                "source_id": "source-1",
                "payload": PassThroughPayload(),
                "documents": "cascade",
                "idempotency_key": "delete-source-once",
            },
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.sync_source,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "syncSource",
            {"source_id": "source-1", "idempotency_key": "sync-source-once"},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.list_source_providers,
            data_facade_module.KnowledgeFSSourceProviderListResponse,
            "listSourceProviders",
            {},
            None,
        ),
        (
            KnowledgeFSDataFacade.create_source_connection,
            data_facade_module.KnowledgeFSSourceConnectionResponse,
            "createSourceConnection",
            {"payload": PassThroughPayload()},
            None,
        ),
        (
            KnowledgeFSDataFacade.list_source_connections,
            data_facade_module.KnowledgeFSSourceConnectionListResponse,
            "listSourceConnections",
            {"cursor": "cursor-1", "limit": 25},
            None,
        ),
        (
            KnowledgeFSDataFacade.refresh_source_connection,
            data_facade_module.KnowledgeFSSourceConnectionResponse,
            "refreshSourceConnection",
            {"connection_id": "connection-1", "payload": PassThroughPayload()},
            None,
        ),
        (
            KnowledgeFSDataFacade.preview_source_crawl,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "previewSourceCrawl",
            {"source_id": "source-1", "idempotency_key": "preview-source-once"},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.import_source_workflow,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "importSourceWorkflow",
            {
                "source_id": "source-1",
                "payload": PassThroughPayload(),
                "idempotency_key": "import-source-once",
            },
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.get_source_sync_policy,
            data_facade_module.KnowledgeFSSourceSyncPolicyResponse,
            "getSourceSyncPolicy",
            {"source_id": "source-1"},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.update_source_sync_policy,
            data_facade_module.KnowledgeFSSourceSyncPolicyResponse,
            "updateSourceSyncPolicy",
            {"source_id": "source-1", "payload": PassThroughPayload()},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.get_source_workflow,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "getSourceWorkflow",
            {"run_id": "run-1"},
            "run-1",
        ),
        (
            KnowledgeFSDataFacade.cancel_source_workflow,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "cancelSourceWorkflow",
            {"run_id": "run-1", "payload": PassThroughPayload()},
            "run-1",
        ),
        (
            KnowledgeFSDataFacade.retry_source_workflow,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "retrySourceWorkflow",
            {"run_id": "run-1"},
            "run-1",
        ),
        (
            KnowledgeFSDataFacade.list_crawl_preview_pages,
            data_facade_module.KnowledgeFSCrawlPreviewPageListResponse,
            "listCrawlPreviewPages",
            {"run_id": "run-1", "cursor": "cursor-1", "limit": 25},
            "run-1",
        ),
        (
            KnowledgeFSDataFacade.select_crawl_preview_pages,
            data_facade_module.KnowledgeFSSourceWorkflowResponse,
            "selectCrawlPreviewPages",
            {"run_id": "run-1", "payload": PassThroughPayload(), "idempotency_key": "selection-once"},
            "run-1",
        ),
        (
            KnowledgeFSDataFacade.crawl_source,
            data_facade_module.KnowledgeFSSourceCrawlResponse,
            "crawlSource",
            {"source_id": "source-1"},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.list_source_pages,
            data_facade_module.KnowledgeFSSourcePagesResponse,
            "listSourcePages",
            {"source_id": "source-1", "cursor": "cursor-1", "limit": 25},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.import_source_pages,
            data_facade_module.KnowledgeFSSourceImportResponse,
            "importSourcePages",
            {"source_id": "source-1", "payload": PassThroughPayload()},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.list_source_files,
            data_facade_module.KnowledgeFSSourceFilesResponse,
            "listSourceFiles",
            {"source_id": "source-1", "query": (("cursor", "cursor-1"),)},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.import_source_files,
            data_facade_module.KnowledgeFSSourceImportResponse,
            "importSourceFiles",
            {"source_id": "source-1", "payload": PassThroughPayload()},
            "source-1",
        ),
        (
            KnowledgeFSDataFacade.plan_research_task,
            data_facade_module.KnowledgeFSResearchTaskPlanResponse,
            "planResearchTask",
            {"payload": PassThroughPayload()},
            None,
        ),
        (
            KnowledgeFSDataFacade.get_research_task,
            data_facade_module.KnowledgeFSResearchTaskResponse,
            "getResearchTask",
            {"task_id": "task-1"},
            "task-1",
        ),
        (
            KnowledgeFSDataFacade.list_research_task_partials,
            data_facade_module.KnowledgeFSResearchTaskPartialListResponse,
            "listResearchTaskPartials",
            {"task_id": "task-1", "cursor": "cursor-1", "limit": 10},
            "task-1",
        ),
        (
            KnowledgeFSDataFacade.cancel_research_task,
            data_facade_module.KnowledgeFSResearchTaskResponse,
            "cancelResearchTask",
            {"task_id": "task-1"},
            "task-1",
        ),
    ],
)
def test_facade_public_methods_preserve_the_registered_operation_and_child_binding(
    method_name: Callable[..., object],
    response_name: type[BaseModel],
    operation_id: str,
    specific_kwargs: dict[str, object],
    child_resource_id: str | None,
) -> None:
    facade = _offline_facade()
    interactive = CallRecorder(result={})
    interactive_child = CallRecorder(result={})
    response_type = response_name
    expected_response = ValidatedResponse()
    common_kwargs = {
        "tenant_id": "tenant-1",
        "account_id": "account-1",
        "control_space_id": "control-1",
    }

    with (
        patch.object(facade, "_interactive", interactive),
        patch.object(facade, "_interactive_child", interactive_child),
        patch.object(response_type, "model_validate", return_value=expected_response) as validate,
    ):
        result = method_name(facade, **common_kwargs, **specific_kwargs)

    assert result is expected_response
    validate.assert_called_once_with({})
    delegated = interactive_child if child_resource_id is not None else interactive
    idle = interactive if child_resource_id is not None else interactive_child
    assert len(delegated.calls) == 1
    assert idle.calls == []
    delegated_kwargs = delegated.last.kwargs
    assert delegated_kwargs["operation_id"] == operation_id
    if "payload" in specific_kwargs:
        assert delegated_kwargs["payload"] is specific_kwargs["payload"]
    if operation_id == "listBackgroundTasks":
        expected_query = (("limit", "25"),)
        if specific_kwargs.get("cursor"):
            expected_query += (("cursor", specific_kwargs["cursor"]),)
        if specific_kwargs.get("task_ids"):
            expected_query += (("taskIds", specific_kwargs["task_ids"]),)
        assert delegated_kwargs["query"] == expected_query

    if child_resource_id is not None:
        assert delegated_kwargs["resource_id"] == child_resource_id
    if operation_id == "listLogicalDocuments":
        assert delegated_kwargs["query"] == (
            ("cursor", "cursor-1"),
            ("limit", "25"),
            ("query", "late report"),
            ("status", "processing"),
        )
    if operation_id == "listDocumentRevisions":
        assert delegated_kwargs["query"] == (("cursor", "cursor-1"), ("limit", "1"))
    if operation_id in {"listGoldenQuestions", "listQualityBadCases"}:
        assert delegated_kwargs["query"] == (("limit", "25"), ("cursor", "cursor-1"))
    if operation_id == "createQualityReplay":
        assert delegated_kwargs["headers"] == (("Idempotency-Key", "quality-replay-once"),)
    if operation_id == "listQualityReplays":
        assert delegated_kwargs["query"] == (
            ("limit", "25"),
            ("cursor", "cursor-1"),
            ("mode", "deep"),
            ("state", "passed"),
        )
    if operation_id == "getQualityReplay":
        assert delegated_kwargs["path_parameters"] == (("runId", "replay-run-1"),)
        assert delegated_kwargs["query"] == (("evidenceItemId", "replay-item-1"),)
    if operation_id == "getOverviewQueryOutcomes":
        assert delegated_kwargs["query"] == (("window", "7d"),)
    if operation_id == "cancelBackgroundTask":
        assert delegated_kwargs["path_parameters"] == (
            ("taskKind", "source"),
            ("taskId", "task-1"),
        )
    if operation_id == "retryBackgroundTask":
        assert delegated_kwargs["path_parameters"] == (
            ("taskKind", "document_bulk"),
            ("taskId", "task-1"),
        )
    if operation_id == "importSourceWorkflow":
        assert delegated_kwargs["path_parameters"] == (("sourceId", "source-1"),)
        assert delegated_kwargs["headers"] == (("Idempotency-Key", "import-source-once"),)


def test_service_settings_migration_preserves_service_identity_on_every_operation() -> None:
    profile = KnowledgeFSServiceApiProfile(
        tenant_id="tenant-1",
        control_space_id="control-1",
        api_token_id="api-token-1",
        principal_id="api-token-1",
        knowledge_space_id="space-1",
        knowledge_space_revision=9,
        membership_epoch=1,
        space_acl_epoch=1,
        external_access_epoch=1,
        content_policy_revision=1,
    )
    remote = ActiveSettingsRemote()
    broker = ServiceBroker()
    facade = KnowledgeFSDataFacade(broker=broker, remote=remote)
    result = facade.update_service_settings(
        profile=profile,
        payload=KnowledgeFSSettingsPayload(
            expected_revision=9,
            embedding=KnowledgeFSProfileModelSelection(model="embed-v2", plugin_id="plugin-2", provider="provider-2"),
        ),
    )
    assert result.migration is not None
    assert result.migration.run_state == "queued"
    assert [call["operation_id"] for call in broker.service_calls] == [
        "getSettings",
        "updateEmbeddingProfile",
    ]
    assert all(call["profile"] is profile for call in broker.service_calls)
    assert [request.path for request in remote.requests] == [
        "/knowledge-spaces/space-1/product-settings",
        "/knowledge-spaces/space-1/embedding-profile",
    ]


def logical_document(
    *,
    active: KnowledgeFSDocumentRevisionResponse | None,
    status: Literal["deleting", "failed", "pending", "ready"] = "ready",
) -> KnowledgeFSLogicalDocumentResponse:
    return KnowledgeFSLogicalDocumentResponse(
        active=active,
        active_revision=active.revision if active else None,
        created_at=datetime.now(UTC),
        enabled=True,
        id="logical-1",
        knowledge_space_id="space-1",
        row_version=1,
        status=status,
        title="Document",
        updated_at=datetime.now(UTC),
        user_metadata={},
    )


def revision(
    *, state: Literal["active", "candidate", "failed", "superseded"] = "active"
) -> KnowledgeFSDocumentRevisionResponse:
    return KnowledgeFSDocumentRevisionResponse(
        activated_at=datetime.now(UTC) if state == "active" else None,
        content_hash="a" * 64,
        created_at=datetime.now(UTC),
        document_asset_id="asset-1",
        document_asset_version=2,
        document_id="logical-1",
        knowledge_space_id="space-1",
        mime_type="text/markdown",
        revision=3,
        size_bytes=4,
        state=state,
    )


def asset() -> KnowledgeFSDocumentResponse:
    return KnowledgeFSDocumentResponse(
        id="asset-1",
        knowledge_space_id="space-1",
        filename="page.md",
        metadata={},
        mime_type="text/markdown",
        object_key="tenant/spaces/space-1/documents/page.md",
        parser_status="parsed",
        sha256="a" * 64,
        size_bytes=4,
        version=2,
        created_at=datetime.now(UTC),
    )


class FakeDownloadFacade(KnowledgeFSDataFacade):
    """Serves canned facade reads and records the calls download preparation makes."""

    def __init__(
        self,
        *,
        logical: KnowledgeFSLogicalDocumentResponse,
        revisions: KnowledgeFSDocumentRevisionListResponse | None = None,
        document: KnowledgeFSDocumentResponse | None = None,
    ) -> None:
        self._logical = logical
        self._revisions = revisions
        self._document = document
        self.get_logical_document_calls: list[dict[str, object]] = []
        self.list_document_revisions_calls: list[dict[str, object]] = []
        self.get_document_calls: list[dict[str, object]] = []

    @override
    def get_logical_document(
        self, *, tenant_id: str, account_id: str, control_space_id: str, document_id: str
    ) -> KnowledgeFSLogicalDocumentResponse:
        self.get_logical_document_calls.append(
            {
                "tenant_id": tenant_id,
                "account_id": account_id,
                "control_space_id": control_space_id,
                "document_id": document_id,
            }
        )
        return self._logical

    @override
    def list_document_revisions(
        self,
        *,
        tenant_id: str,
        account_id: str,
        control_space_id: str,
        document_id: str,
        cursor: str | None = None,
        limit: int | None = None,
    ) -> KnowledgeFSDocumentRevisionListResponse:
        self.list_document_revisions_calls.append(
            {
                "tenant_id": tenant_id,
                "account_id": account_id,
                "control_space_id": control_space_id,
                "document_id": document_id,
                "cursor": cursor,
                "limit": limit,
            }
        )
        assert self._revisions is not None
        return self._revisions

    @override
    def get_document(
        self, *, tenant_id: str, account_id: str, control_space_id: str, document_id: str
    ) -> KnowledgeFSDocumentResponse:
        self.get_document_calls.append(
            {
                "tenant_id": tenant_id,
                "account_id": account_id,
                "control_space_id": control_space_id,
                "document_id": document_id,
            }
        )
        assert self._document is not None
        return self._document


def test_prepare_logical_document_download_resolves_active_asset() -> None:
    facade = FakeDownloadFacade(logical=logical_document(active=revision()), document=asset())

    result = facade.prepare_logical_document_download(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        document_id="logical-1",
    )

    assert result.document_id == "logical-1"
    assert result.object_key == "tenant/spaces/space-1/documents/page.md"
    assert facade.list_document_revisions_calls == []
    assert facade.get_document_calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "document_id": "asset-1",
        }
    ]


def test_prepare_logical_document_download_resolves_latest_failed_revision_without_active_revision() -> None:
    facade = FakeDownloadFacade(
        logical=logical_document(active=None, status="failed"),
        revisions=KnowledgeFSDocumentRevisionListResponse(data=[revision(state="failed")]),
        document=asset(),
    )

    result = facade.prepare_logical_document_download(
        tenant_id="tenant-1",
        account_id="account-1",
        control_space_id="control-1",
        document_id="logical-1",
    )

    assert result.document_id == "logical-1"
    assert result.object_key == "tenant/spaces/space-1/documents/page.md"
    assert facade.list_document_revisions_calls == [
        {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "document_id": "logical-1",
            "cursor": None,
            "limit": 1,
        }
    ]


def test_prepare_logical_document_download_rejects_document_without_visible_revision() -> None:
    facade = FakeDownloadFacade(
        logical=logical_document(active=None, status="failed"),
        revisions=KnowledgeFSDocumentRevisionListResponse(data=[]),
    )

    with pytest.raises(KnowledgeFSProductResourceNotFoundError):
        facade.prepare_logical_document_download(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            document_id="logical-1",
        )


def test_prepare_logical_document_download_rejects_latest_candidate_revision() -> None:
    facade = FakeDownloadFacade(
        logical=logical_document(active=None, status="failed"),
        revisions=KnowledgeFSDocumentRevisionListResponse(data=[revision(state="candidate")]),
    )

    with pytest.raises(KnowledgeFSProductResourceNotFoundError):
        facade.prepare_logical_document_download(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            document_id="logical-1",
        )

    assert facade.get_document_calls == []


def test_prepare_logical_document_download_rejects_pending_document_without_active_revision() -> None:
    facade = FakeDownloadFacade(logical=logical_document(active=None, status="pending"))

    with pytest.raises(KnowledgeFSProductResourceNotFoundError):
        facade.prepare_logical_document_download(
            tenant_id="tenant-1",
            account_id="account-1",
            control_space_id="control-1",
            document_id="logical-1",
        )

    assert facade.list_document_revisions_calls == []
    assert facade.get_document_calls == []