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.

177 KB
Raw Blame
from __future__ import annotations

import ast
import inspect
from collections.abc import Callable, Generator
from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import UTC, datetime
from hashlib import sha256
from http import HTTPStatus
from inspect import unwrap
from io import BytesIO
from pathlib import Path
from types import FunctionType
from typing import Literal, Never, cast

import pytest
from flask import Flask
from flask_restx import Resource
from pydantic import BaseModel
from werkzeug.exceptions import Forbidden, NotFound, ServiceUnavailable

from controllers.common import wraps as common_wraps
from controllers.console import console_ns, flask_admission, wraps
from controllers.console import wraps as console_wraps
from controllers.console.knowledge_fs import resources
from controllers.console.knowledge_fs import resources as console_resources
from controllers.console.knowledge_fs.error import (
    KnowledgeFSAccessDeniedHTTPError,
    KnowledgeFSConflictHTTPError,
    KnowledgeFSInvalidRequestHTTPError,
    KnowledgeFSOperationUnavailableHTTPError,
    KnowledgeFSRateLimitHTTPError,
    KnowledgeFSRequestRejectedHTTPError,
    KnowledgeFSRequestTooLargeHTTPError,
    KnowledgeFSResourceNotFoundHTTPError,
    KnowledgeFSSpaceNotFoundHTTPError,
    KnowledgeFSTimeoutHTTPError,
    KnowledgeFSUpstreamUnavailableHTTPError,
)
from controllers.console.wraps import RBACPermission as _knowledge_fs_product_controllers_RBACPermission
from controllers.service_api import service_api_ns
from controllers.service_api.knowledge_fs import resources as service_resources
from controllers.service_api.knowledge_fs.error import (
    KnowledgeFSInvalidCredentialHTTPError,
    KnowledgeFSServiceAccessDeniedHTTPError,
    KnowledgeFSServiceConflictHTTPError,
    KnowledgeFSServiceInvalidRequestHTTPError,
    KnowledgeFSServiceOperationUnavailableHTTPError,
    KnowledgeFSServiceRateLimitHTTPError,
    KnowledgeFSServiceRequestRejectedHTTPError,
    KnowledgeFSServiceRequestTooLargeHTTPError,
    KnowledgeFSServiceResourceNotFoundHTTPError,
    KnowledgeFSServiceUpstreamUnavailableHTTPError,
)
from core.rbac.entities import RBACPermission as _knowledge_fs_creation_RBACPermission
from enums import DeploymentEdition
from libs import login
from libs.exception import BaseHTTPException
from libs.login import AccountWithTenant
from machinery.context import RequestContext
from models import Account
from models.account import TenantAccountRole
from models.enums import ApiTokenType
from models.knowledge_fs import KnowledgeFSAppSpaceJoinType, KnowledgeFSControlSpaceState
from models.model import ApiToken
from services.enterprise.rbac_service import RBACService
from services.knowledge_fs import source_edit_service
from services.knowledge_fs.capability_broker import KnowledgeFSIssuedProductCapability
from services.knowledge_fs.control_space_commands import KnowledgeFSControlSpaceIntentConflictError
from services.knowledge_fs.download_service import KnowledgeFSDownloadUnavailableError
from services.knowledge_fs.object_storage import KnowledgeFSObjectMetadata
from services.knowledge_fs.product_dto import (
    KnowledgeFSAdmittedQueryRequest,
    KnowledgeFSAtomicSourceUpdatePayload,
    KnowledgeFSDocumentDownloadDescriptor,
    KnowledgeFSDocumentMultimodalManifest,
    KnowledgeFSDocumentStagedUploadAcceptedResponse,
    KnowledgeFSDocumentStagedUploadPayload,
    KnowledgeFSDocumentUploadAcceptedResponse,
    KnowledgeFSDurableDeletionAcceptedResponse,
    KnowledgeFSLogicalDocumentDeletePayload,
    KnowledgeFSNamespacePreviewJobResponse,
    KnowledgeFSNamespacePreviewPageResponse,
    KnowledgeFSOverviewBaseStatsResponse,
    KnowledgeFSOverviewQueryOutcomesResponse,
    KnowledgeFSOverviewStatsResponse,
    KnowledgeFSPublicFailureResponse,
    KnowledgeFSQueryAdmissionResponse,
    KnowledgeFSQueryCreatePayload,
    KnowledgeFSQueryStreamCapabilityResponse,
    KnowledgeFSSmallFileUploadResponse,
    KnowledgeFSSourceImportConfigurationPayload,
    KnowledgeFSSourceResponse,
    KnowledgeFSSourceSyncPolicyResponse,
    KnowledgeFSSourceUpdatePayload,
    KnowledgeFSSourceWorkflowResponse,
    KnowledgeFSSpaceCreatePayload,
    KnowledgeFSSpaceCreateResponse,
    KnowledgeFSStagedUploadResponse,
    KnowledgeFSStreamCapabilityPayload,
    KnowledgeFSStreamCapabilityResponse,
)
from services.knowledge_fs.product_remote import (
    KnowledgeFSOperationUnavailableError,
    KnowledgeFSProductRequestRejectedError,
    KnowledgeFSProductResourceNotFoundError,
    KnowledgeFSRemoteMultipartFile,
    KnowledgeFSRemoteSSEResponse,
)
from services.knowledge_fs.runtime import KnowledgeFSRuntime
from services.knowledge_fs.service_api_authorization import (
    KnowledgeFSServiceApiAuthorizationError,
    KnowledgeFSServiceApiProfile,
    KnowledgeFSServiceApiScopeError,
)
from tests.helpers.unit.config_override import apply_config_overrides
from tests.helpers.unit.controllers.knowledge_fs_controller_fakes import (
    FakeComponent,
    FakeRuntime,
    Recorder,
    invocation,
    narrowed,
    raising,
)
from tests.helpers.unit.model_factories import make_account

"""KnowledgeFS creation must preserve legacy roles and Enterprise RBAC admission."""


class TestKnowledgeFsCreationCases:
    @staticmethod
    @pytest.mark.parametrize(
        ("role", "rbac_enabled", "rbac_allowed", "allowed"),
        [
            (TenantAccountRole.NORMAL, False, True, False),
            (None, False, True, False),
            (TenantAccountRole.OWNER, False, True, True),
            (TenantAccountRole.ADMIN, False, True, True),
            (TenantAccountRole.EDITOR, False, True, True),
            (TenantAccountRole.DATASET_OPERATOR, False, True, True),
            (TenantAccountRole.NORMAL, True, True, True),
            (TenantAccountRole.ADMIN, True, False, False),
        ],
    )
    def test_create_space_enforces_admission_before_provisioning(
        app: Flask,
        monkeypatch: pytest.MonkeyPatch,
        config_overrides: Callable[..., None],
        role: TenantAccountRole | None,
        rbac_enabled: bool,
        rbac_allowed: bool,
        allowed: bool,
    ) -> None:
        config_overrides(
            DEPLOYMENT_EDITION=DeploymentEdition.CLOUD,
            KNOWLEDGE_FS_ENABLED=True,
            RBAC_ENABLED=rbac_enabled,
            LOGIN_DISABLED=False,
        )
        account = make_account(role=role)
        identity = AccountWithTenant(account, "workspace")
        monkeypatch.setattr(login, "_resolve_current_user", lambda: account)
        monkeypatch.setattr(login, "check_csrf_token", lambda _request, _user_id: None)
        monkeypatch.setattr(wraps, "current_account_with_tenant", lambda: identity)
        monkeypatch.setattr(flask_admission, "current_account_with_tenant", lambda: identity)
        monkeypatch.setattr(resources, "current_account_with_tenant", lambda: identity)
        monkeypatch.setattr(wraps, "check_knowledge_rate_limit", lambda: None)
        check_access = Recorder(rbac_allowed)
        monkeypatch.setattr(RBACService.CheckAccess, "check", check_access)
        create_space = Recorder(
            KnowledgeFSSpaceCreateResponse(
                control_space_id="space",
                state=KnowledgeFSControlSpaceState.PROVISIONING,
                operation_id="operation",
                model_setup_required=True,
            )
        )
        runtime = FakeRuntime(application=FakeComponent(create_space=create_space))
        monkeypatch.setattr(resources, "_console_services", lambda: runtime)

        with app.test_request_context("/knowledge-fs/spaces", method="POST", json={"name": "Test", "slug": "test"}):
            if allowed:
                result, status = narrowed(resources.KnowledgeFSSpacesApi().post(), tuple)
                assert status == HTTPStatus.ACCEPTED
                assert result["control_space_id"] == "space"
            else:
                with pytest.raises(Forbidden):
                    resources.KnowledgeFSSpacesApi().post()

        if allowed:
            assert create_space.only_call.kwargs["tenant_id"] == "workspace"
            assert create_space.only_call.kwargs["account_id"] == account.id
        else:
            assert not create_space.calls
        if rbac_enabled:
            assert check_access.only_call == invocation(
                "workspace",
                account.id,
                scene=_knowledge_fs_creation_RBACPermission.DATASET_CREATE_AND_MANAGEMENT.value,
                resource_type=None,
                resource_id=None,
            )
        else:
            assert not check_access.calls


_API_ROOT = Path(__file__).resolve().parents[5]


@dataclass(frozen=True)
class _FacadeRuntime[T]:
    facade: T


@dataclass(frozen=True)
class _BrokerRuntime[T]:
    broker: T


def _knowledge_fs_product_controllers_account(account_id: str = "account-1") -> Account:
    account = Account(name="Test User", email="[email protected]")
    account.id = account_id
    return account


def _dataset_api_token(tenant_id: str | None = "tenant-1") -> ApiToken:
    api_token = ApiToken()
    api_token.id = "token-1"
    api_token.tenant_id = tenant_id
    api_token.type = ApiTokenType.DATASET
    api_token.token = "dataset-test-key"
    return api_token


def _issued_capability(
    *, token: str, operation_id: str, knowledge_space_id: str = "space-1"
) -> KnowledgeFSIssuedProductCapability:
    return KnowledgeFSIssuedProductCapability(
        token=token,
        expires_at=datetime(2030, 1, 1, tzinfo=UTC),
        operation_id=operation_id,
        knowledge_space_id=knowledge_space_id,
        knowledge_space_revision=1,
        trace_id="trace-1",
    )


def _service_profile(control_space_id: str) -> KnowledgeFSServiceApiProfile:
    return KnowledgeFSServiceApiProfile(
        tenant_id="tenant-1",
        control_space_id=control_space_id,
        api_token_id="token-1",
        principal_id="token-1",
        knowledge_space_id="space-1",
        knowledge_space_revision=1,
        membership_epoch=0,
        space_acl_epoch=0,
        external_access_epoch=0,
        content_policy_revision=0,
    )


def _rbac_wrapper(view: FunctionType) -> FunctionType:
    current = inspect.unwrap(
        view,
        stop=lambda candidate: (
            isinstance(candidate, FunctionType) and "rbac_permission_required" in candidate.__code__.co_qualname
        ),
    )
    assert isinstance(current, FunctionType)
    assert "rbac_permission_required" in current.__code__.co_qualname, "RBAC permission wrapper is missing"
    return current


def _document_multimodal_manifest(*, object_key: str | None = None) -> KnowledgeFSDocumentMultimodalManifest:
    asset_ref = (
        {
            "contentType": "image/png",
            "objectKey": object_key,
            "sha256": "a" * 64,
            "variants": {
                "thumbnail": {
                    "contentType": "image/webp",
                    "objectKey": object_key.replace("full.png", "thumbnail.webp"),
                    "sha256": "b" * 64,
                }
            },
        }
        if object_key is not None
        else None
    )
    return KnowledgeFSDocumentMultimodalManifest.model_validate(
        {
            "artifactHash": "c" * 64,
            "createdAt": "2026-08-14T12:00:00.000Z",
            "documentAssetId": "018f0d60-7a49-7cc2-9c1b-5b36f18f2c44",
            "id": "018f0d60-7a49-7cc2-9c1b-5b36f18f2c45",
            "items": [
                {
                    "assetRef": asset_ref,
                    "caption": "Architecture",
                    "endOffset": 42,
                    "id": "figure:1",
                    "modality": "image",
                    "ocrText": "Service A to Service B",
                    "pageNumber": 2,
                    "parseElementId": "parse-element-1",
                    "sectionPath": ["Architecture"],
                    "startOffset": 42,
                    "title": "System diagram",
                }
            ],
            "knowledgeSpaceId": "018f0d60-7a49-7cc2-9c1b-5b36f18f2c43",
            "manifestVersion": "document-multimodal@1",
            "updatedAt": "2026-08-14T12:01:00.000Z",
            "version": 3,
        }
    )


class TestKnowledgeFsProductControllersCases:
    @staticmethod
    @pytest.fixture(autouse=True)
    def _enabled_knowledge_fs(config_overrides: Callable[..., None]) -> None:
        config_overrides(
            DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY,
            KNOWLEDGE_FS_ENABLED=True,
            KNOWLEDGE_FS_COMMUNITY_DEV_ENABLED=True,
        )

    @staticmethod
    def test_disabled_knowledge_fs_rejects_console_work_before_preview_upload_or_query_admission(
        config_overrides: Callable[..., None],
    ) -> None:
        config_overrides(KNOWLEDGE_FS_ENABLED=False)
        routes = (
            (
                console_resources.KnowledgeFSInitialSourcePreviewApi,
                console_resources.KnowledgeFSInitialSourcePreviewApi.post,
                (),
            ),
            (
                console_resources.KnowledgeFSInitialSourcePreviewJobsApi,
                console_resources.KnowledgeFSInitialSourcePreviewJobsApi.post,
                (),
            ),
            (console_resources.KnowledgeFSStagedUploadsApi, console_resources.KnowledgeFSStagedUploadsApi.post, ()),
            (
                console_resources.KnowledgeFSSpaceQueryAdmissionApi,
                console_resources.KnowledgeFSSpaceQueryAdmissionApi.post,
                ("space-1",),
            ),
        )
        for resource_type, view, args in routes:
            handler = inspect.unwrap(
                view,
                stop=lambda view: "_knowledge_fs_errors.<locals>.decorated" in view.__code__.co_qualname,
            )
            with pytest.raises(NotFound):
                handler(resource_type(), *args)

    @staticmethod
    def test_disabled_knowledge_fs_hides_jwks_even_when_capability_v2_is_configured(
        config_overrides: Callable[..., None],
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        config_overrides(KNOWLEDGE_FS_ENABLED=False, KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=True)
        monkeypatch.setattr(
            console_resources.session_factory,
            "get_session_maker",
            lambda: pytest.fail("disabled JWKS must not access the database"),
        )
        with pytest.raises(NotFound):
            console_resources.KnowledgeFSJWKSApi().get()

    @staticmethod
    def test_disabled_knowledge_fs_rejects_service_api_before_token_validation(
        config_overrides: Callable[..., None],
    ) -> None:
        config_overrides(KNOWLEDGE_FS_ENABLED=False)
        handler = inspect.unwrap(
            service_resources.KnowledgeFSServiceSourceProvidersApi.get,
            stop=lambda view: "_service_api_errors.<locals>.decorated" in view.__code__.co_qualname,
        )
        with pytest.raises(NotFound):
            handler(service_resources.KnowledgeFSServiceSourceProvidersApi(), "space-1")

    @staticmethod
    def test_console_and_service_api_routes_are_registered() -> None:
        console_urls = {url for route in console_ns.resources for url in route.urls if url.startswith("/knowledge-fs/")}
        service_urls = {
            url for route in service_api_ns.resources for url in route.urls if url.startswith("/knowledge-fs/")
        }

        assert {
            "/knowledge-fs/spaces",
            "/knowledge-fs/uploads",
            "/knowledge-fs/uploads/<string:upload_id>",
            "/knowledge-fs/spaces/<string:control_space_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/tags",
            "/knowledge-fs/spaces/<string:control_space_id>/permissions",
            "/knowledge-fs/spaces/<string:control_space_id>/members",
            "/knowledge-fs/spaces/<string:control_space_id>/app-bindings",
            ("/knowledge-fs/spaces/<string:control_space_id>/app-bindings/<string:caller_kind>/<string:app_id>"),
            "/knowledge-fs/spaces/<string:control_space_id>/external-access",
            "/knowledge-fs/spaces/<string:control_space_id>/settings",
            "/knowledge-fs/spaces/<string:control_space_id>/documents",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/multimodal",
            (
                "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/multimodal/"
                "<path:item_id>/asset"
            ),
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/download-zip",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/<string:document_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/<string:document_id>/download",
            "/knowledge-fs/spaces/<string:control_space_id>/sources",
            "/knowledge-fs/spaces/<string:control_space_id>/source-connections",
            "/knowledge-fs/spaces/<string:control_space_id>/source-providers",
            ("/knowledge-fs/spaces/<string:control_space_id>/source-connections/<string:connection_id>/refresh"),
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/sync",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/crawl-preview",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/workflow-imports",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/sync-policy",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/cancel",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/retry",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/pages",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/selection",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/async-import",
            "/knowledge-fs/spaces/<string:control_space_id>/queries",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks",
            "/knowledge-fs/spaces/<string:control_space_id>/traces",
            "/knowledge-fs/spaces/<string:control_space_id>/golden-questions/bulk-import",
            "/knowledge-fs/spaces/<string:control_space_id>/golden-questions/evidence-matches",
            "/knowledge-fs/spaces/<string:control_space_id>/upload-sessions",
            (
                "/knowledge-fs/spaces/<string:control_space_id>/upload-sessions/"
                "<string:upload_session_id>/parts/<int:part_number>/presign"
            ),
            ("/knowledge-fs/spaces/<string:control_space_id>/upload-sessions/<string:upload_session_id>/complete"),
            ("/knowledge-fs/spaces/<string:control_space_id>/upload-sessions/<string:upload_session_id>/abort"),
            ("/knowledge-fs/spaces/<string:control_space_id>/upload-sessions/<string:upload_session_id>/small-file"),
            "/knowledge-fs/spaces/<string:control_space_id>/query-stream-capability",
            "/knowledge-fs/tasks/<string:task_id>/stream-capability",
            "/knowledge-fs/query-stream",
            "/knowledge-fs/research-tasks/<string:task_id>/events",
            "/knowledge-fs/.well-known/jwks.json",
        }.issubset(console_urls)
        assert service_urls == {
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/<string:document_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/document-references/resolve",
            "/knowledge-fs/spaces/<string:control_space_id>/deletion-jobs/<string:job_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/deletion-jobs/<string:job_id>/retry",
            "/knowledge-fs/spaces/<string:control_space_id>/deletion-batches/<string:batch_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks/<string:task_id>/resume",
            "/knowledge-fs/spaces/<string:control_space_id>/background-tasks",
            "/knowledge-fs/spaces/<string:control_space_id>/settings/migrations/<string:migration_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/sync",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/crawl-preview",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/crawl-import",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/workflow-imports",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/sync-policy",
            "/knowledge-fs/spaces/<string:control_space_id>/source-connections",
            "/knowledge-fs/spaces/<string:control_space_id>/source-providers",
            "/knowledge-fs/spaces/<string:control_space_id>/query-images",
            "/knowledge-fs/spaces/<string:control_space_id>/source-connections/<string:connection_id>/refresh",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/cancel",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/retry",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/pages",
            "/knowledge-fs/spaces/<string:control_space_id>/source-workflows/<string:run_id>/selection",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/<string:document_id>/processing-tasks",
            "/knowledge-fs/spaces/<string:control_space_id>/logical-documents/<string:document_id>/processing-tasks/<string:task_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/bulk-jobs/<string:job_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/documents",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/outline",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/revisions",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/revisions/<int:revision>/chunks",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/<string:document_id>/revisions/<int:revision>/chunks/<string:chunk_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/bulk",
            "/knowledge-fs/spaces/<string:control_space_id>/documents/reindex",
            "/knowledge-fs/spaces/<string:control_space_id>/jobs/<string:job_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/jobs/<string:job_id>/retry",
            "/knowledge-fs/spaces/<string:control_space_id>/queries/admission",
            "/knowledge-fs/query-stream",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks/<string:task_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks/<string:task_id>/partials",
            "/knowledge-fs/spaces/<string:control_space_id>/research-tasks/plan",
            "/knowledge-fs/spaces/<string:control_space_id>/settings",
            "/knowledge-fs/spaces/<string:control_space_id>/sources",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/crawl",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/files",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/import",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/import-files",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/pages",
            "/knowledge-fs/spaces/<string:control_space_id>/sources/<string:source_id>/test",
            "/knowledge-fs/spaces/<string:control_space_id>/traces",
            "/knowledge-fs/spaces/<string:control_space_id>/traces/<string:trace_id>",
            "/knowledge-fs/spaces/<string:control_space_id>/traces/<string:trace_id>/conflicts",
            "/knowledge-fs/spaces/<string:control_space_id>/traces/<string:trace_id>/evidence",
            "/knowledge-fs/spaces/<string:control_space_id>/traces/<string:trace_id>/missing",
        }

    @staticmethod
    def test_initial_website_preview_job_routes_delegate_to_namespace_capabilities(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        account = _knowledge_fs_product_controllers_account()
        preview_service = FakeComponent(require_visible_credential=Recorder())
        facade = FakeComponent(
            create_namespace_source_preview=Recorder(
                KnowledgeFSNamespacePreviewJobResponse(
                    job_id="job-1",
                    status="queued",
                    configuration_fingerprint="f" * 64,
                    expires_at="2030-01-01T00:00:00Z",
                )
            ),
            get_namespace_source_preview=Recorder(
                KnowledgeFSNamespacePreviewJobResponse(
                    job_id="job-1",
                    status="completed",
                    configuration_fingerprint="f" * 64,
                    expires_at="2030-01-01T00:00:00Z",
                    pages=[
                        KnowledgeFSNamespacePreviewPageResponse(
                            page_id="page-1",
                            source_url="https://example.com/page",
                            title="Page",
                        )
                    ],
                )
            ),
            cancel_namespace_source_preview=Recorder(
                KnowledgeFSNamespacePreviewJobResponse(
                    job_id="job-1",
                    status="consumed",
                    configuration_fingerprint="f" * 64,
                    expires_at="2030-01-01T00:00:00Z",
                )
            ),
        )
        monkeypatch.setattr(console_resources, "current_account_with_tenant", lambda: (account, "tenant-1"))
        monkeypatch.setattr(console_resources, "KnowledgeFSInitialSourcePreviewService", lambda _: preview_service)
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        app = Flask(__name__)

        with app.test_request_context(
            method="POST",
            json={
                "kind": "website_crawl",
                "credentialId": "credential-1",
                "datasource": "website",
                "pluginId": "plugin-1",
                "provider": "firecrawl",
                "parameters": {"url": "https://example.com"},
            },
        ):
            response, status = inspect.unwrap(console_resources.KnowledgeFSInitialSourcePreviewJobsApi.post)(
                console_resources.KnowledgeFSInitialSourcePreviewJobsApi()
            )
        assert status == 202
        assert response == {"job_id": "job-1", "status": "pending"}
        assert len(preview_service.require_visible_credential.calls) == 1
        assert len(facade.create_namespace_source_preview.calls) == 1

        with app.test_request_context():
            response = inspect.unwrap(console_resources.KnowledgeFSInitialSourcePreviewJobApi.get)(
                console_resources.KnowledgeFSInitialSourcePreviewJobApi(), "job-1"
            )
        assert response["status"] == "completed"
        assert response["result"]["pages"] == [
            {
                "description": None,
                "page_id": "page-1",
                "source_url": "https://example.com/page",
                "title": "Page",
            }
        ]

        facade.get_namespace_source_preview.return_value = KnowledgeFSNamespacePreviewJobResponse(
            job_id="job-1",
            status="queued",
            configuration_fingerprint="f" * 64,
            expires_at="2030-01-01T00:00:00Z",
        )
        with app.test_request_context():
            response = inspect.unwrap(console_resources.KnowledgeFSInitialSourcePreviewJobApi.get)(
                console_resources.KnowledgeFSInitialSourcePreviewJobApi(), "job-1"
            )
        assert response["status"] == "pending"
        assert response["result"] is None

        with app.test_request_context(method="DELETE"):
            response = inspect.unwrap(console_resources.KnowledgeFSInitialSourcePreviewJobApi.delete)(
                console_resources.KnowledgeFSInitialSourcePreviewJobApi(), "job-1"
            )
        assert response == {"job_id": "job-1", "result": None, "status": "completed"}

    @staticmethod
    @pytest.mark.parametrize(
        ("api_class", "method_name", "path_args"),
        [
            (
                console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi,
                console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi.get,
                {"control_space_id": "control-1", "document_id": "document-1"},
            ),
            (
                console_resources.KnowledgeFSSpaceLogicalDocumentsDownloadApi,
                console_resources.KnowledgeFSSpaceLogicalDocumentsDownloadApi.post,
                {"control_space_id": "control-1"},
            ),
        ],
    )
    def test_document_download_routes_deny_callers_without_dataset_download_permission(
        monkeypatch: pytest.MonkeyPatch,
        api_class: type,
        method_name: FunctionType,
        path_args: dict[str, str],
    ) -> None:
        permission_gate = Recorder(raises=Forbidden())
        apply_config_overrides(monkeypatch, RBAC_ENABLED=True)
        monkeypatch.setattr(
            common_wraps,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_product_controllers_account(), "tenant-1"),
        )
        monkeypatch.setattr("controllers.common.rbac.checks.RBACService.CheckAccess.check", permission_gate)
        # The download routes carry the knowledge rate limit too; it needs a logged-in account.
        monkeypatch.setattr(console_wraps, "check_knowledge_rate_limit", lambda: None)
        monkeypatch.setattr(
            console_resources,
            "_console_services",
            lambda: pytest.fail("permission denial must happen before KnowledgeFS access"),
        )

        permission_wrapper = _rbac_wrapper(method_name)
        with pytest.raises(Forbidden):
            permission_wrapper(api_class(), **path_args)

        assert permission_gate.calls == [
            invocation(
                "tenant-1",
                "account-1",
                scene=_knowledge_fs_product_controllers_RBACPermission.DATASET_DOCUMENT_DOWNLOAD,
                resource_type=None,
                resource_id=None,
            )
        ]

    @staticmethod
    def test_single_document_download_allows_dataset_download_permission_and_keeps_tenant_scope(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        descriptor = KnowledgeFSDocumentDownloadDescriptor(
            document_id="document-1",
            filename="guide.md",
            mime_type="text/markdown",
            object_key="namespaces/tenant-1/spaces/space-1/documents/guide.md",
            sha256="a" * 64,
            size_bytes=4,
        )
        facade = FakeComponent(prepare_logical_document_download=Recorder(descriptor))
        download_service = FakeComponent(load_stream=Recorder(iter((b"body",))))
        permission_gate = Recorder(True)
        apply_config_overrides(monkeypatch, RBAC_ENABLED=True)
        monkeypatch.setattr(
            common_wraps,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_product_controllers_account(), "tenant-1"),
        )
        monkeypatch.setattr("controllers.common.rbac.checks.RBACService.CheckAccess.check", permission_gate)
        # The download routes carry the knowledge rate limit too; it needs a logged-in account.
        monkeypatch.setattr(console_wraps, "check_knowledge_rate_limit", lambda: None)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSDownloadService", lambda: download_service)
        permission_wrapper = _rbac_wrapper(console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi.get)
        app = Flask(__name__)

        with app.test_request_context():
            response = permission_wrapper(
                console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi(),
                control_space_id="control-1",
                document_id="document-1",
            )

        assert response.get_data() == b"body"
        assert response.headers["Content-Disposition"] == "attachment; filename*=UTF-8''guide.md"
        assert permission_gate.calls == [
            invocation(
                "tenant-1",
                "account-1",
                scene=_knowledge_fs_product_controllers_RBACPermission.DATASET_DOCUMENT_DOWNLOAD,
                resource_type=None,
                resource_id=None,
            )
        ]
        assert facade.prepare_logical_document_download.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="control-1",
                document_id="document-1",
            )
        ]

    @staticmethod
    def test_single_document_download_preserves_resource_not_found_after_permission_allows(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        facade = FakeComponent(
            prepare_logical_document_download=Recorder(
                raises=KnowledgeFSProductResourceNotFoundError("document not found")
            )
        )
        permission_gate = Recorder(True)
        download_service_factory = Recorder()
        apply_config_overrides(monkeypatch, RBAC_ENABLED=True)
        monkeypatch.setattr(
            common_wraps,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_product_controllers_account(), "tenant-1"),
        )
        monkeypatch.setattr("controllers.common.rbac.checks.RBACService.CheckAccess.check", permission_gate)
        # The download routes carry the knowledge rate limit too; it needs a logged-in account.
        monkeypatch.setattr(console_wraps, "check_knowledge_rate_limit", lambda: None)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSDownloadService", download_service_factory)
        permission_wrapper = _rbac_wrapper(console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi.get)
        app = Flask(__name__)

        with app.test_request_context(), pytest.raises(KnowledgeFSResourceNotFoundHTTPError):
            permission_wrapper(
                console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi(),
                control_space_id="foreign-control",
                document_id="document-1",
            )

        assert len(permission_gate.calls) == 1
        assert facade.prepare_logical_document_download.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="foreign-control",
                document_id="document-1",
            )
        ]
        assert download_service_factory.calls == []

    @staticmethod
    def test_single_document_download_maps_storage_unavailable_after_permission_allows(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        descriptor = KnowledgeFSDocumentDownloadDescriptor(
            document_id="document-1",
            filename="guide.md",
            mime_type="text/markdown",
            object_key="namespaces/tenant-1/spaces/space-1/documents/guide.md",
            sha256="a" * 64,
            size_bytes=4,
        )
        facade = FakeComponent(prepare_logical_document_download=Recorder(descriptor))
        download_service = FakeComponent(
            load_stream=Recorder(raises=KnowledgeFSDownloadUnavailableError("storage unavailable"))
        )
        permission_gate = Recorder(True)
        apply_config_overrides(monkeypatch, RBAC_ENABLED=True)
        monkeypatch.setattr(
            common_wraps,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_product_controllers_account(), "tenant-1"),
        )
        monkeypatch.setattr("controllers.common.rbac.checks.RBACService.CheckAccess.check", permission_gate)
        # The download routes carry the knowledge rate limit too; it needs a logged-in account.
        monkeypatch.setattr(console_wraps, "check_knowledge_rate_limit", lambda: None)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSDownloadService", lambda: download_service)
        permission_wrapper = _rbac_wrapper(console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi.get)
        app = Flask(__name__)

        with app.test_request_context(), pytest.raises(ServiceUnavailable):
            permission_wrapper(
                console_resources.KnowledgeFSSpaceLogicalDocumentDownloadApi(),
                control_space_id="control-1",
                document_id="document-1",
            )

        assert len(permission_gate.calls) == 1
        assert download_service.load_stream.calls == [invocation(descriptor)]

    @staticmethod
    def test_batch_document_download_maps_storage_unavailable_after_permission_allows(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        descriptor = KnowledgeFSDocumentDownloadDescriptor(
            document_id="document-1",
            filename="guide.md",
            mime_type="text/markdown",
            object_key="namespaces/tenant-1/spaces/space-1/documents/guide.md",
            sha256="a" * 64,
            size_bytes=4,
        )
        facade = FakeComponent(prepare_logical_document_download=Recorder(descriptor))

        @contextmanager
        def unavailable_zip() -> Generator[Never]:
            raise KnowledgeFSDownloadUnavailableError("storage unavailable")
            yield

        download_service = FakeComponent(build_zip_tempfile=Recorder(unavailable_zip()))
        permission_gate = Recorder(True)
        apply_config_overrides(monkeypatch, RBAC_ENABLED=True)
        monkeypatch.setattr(
            common_wraps,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_product_controllers_account(), "tenant-1"),
        )
        monkeypatch.setattr("controllers.common.rbac.checks.RBACService.CheckAccess.check", permission_gate)
        # The download routes carry the knowledge rate limit too; it needs a logged-in account.
        monkeypatch.setattr(console_wraps, "check_knowledge_rate_limit", lambda: None)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSDownloadService", lambda: download_service)
        permission_wrapper = _rbac_wrapper(console_resources.KnowledgeFSSpaceLogicalDocumentsDownloadApi.post)
        app = Flask(__name__)

        with (
            app.test_request_context(json={"document_ids": ["document-1"]}),
            pytest.raises(ServiceUnavailable),
        ):
            permission_wrapper(
                console_resources.KnowledgeFSSpaceLogicalDocumentsDownloadApi(),
                control_space_id="control-1",
            )

        assert len(permission_gate.calls) == 1
        assert download_service.build_zip_tempfile.calls == [invocation([descriptor])]

    @staticmethod
    def test_knowledge_fs_request_and_response_schemas_are_registered() -> None:
        assert {
            "KnowledgeFSSpaceCreatePayload",
            "KnowledgeFSAppBindingPayload",
            "KnowledgeFSAppBindingListResponse",
            "KnowledgeFSSpaceUpdatePayload",
            "KnowledgeFSMembersReplacePayload",
            "KnowledgeFSExternalAccessPayload",
            "KnowledgeFSSettingsPayload",
            "KnowledgeFSSourceCreatePayload",
            "KnowledgeFSQueryCreatePayload",
            "KnowledgeFSQueryStreamCapabilityResponse",
            "KnowledgeFSResearchTaskCreatePayload",
            "KnowledgeFSStreamCapabilityPayload",
            "KnowledgeFSSpaceListResponse",
            "KnowledgeFSSpaceDetailResponse",
            "KnowledgeFSDocumentStagedUploadPayload",
            "KnowledgeFSDocumentStagedUploadAcceptedResponse",
            "KnowledgeFSDocumentMultimodalAssetQuery",
            "KnowledgeFSDocumentMultimodalManifestResponse",
            "KnowledgeFSStreamCapabilityResponse",
            "KnowledgeFSJWKSResponse",
            "KnowledgeFSSmallFileUploadResponse",
            "KnowledgeFSCrawlPreviewPageListQuery",
            "KnowledgeFSCrawlPreviewPageListResponse",
            "KnowledgeFSCrawlPreviewSelectionPayload",
            "KnowledgeFSSourceConnectionCreatePayload",
            "KnowledgeFSSourceConnectionListQuery",
            "KnowledgeFSSourceConnectionListResponse",
            "KnowledgeFSSourceConnectionRefreshPayload",
            "KnowledgeFSSourceProviderListResponse",
            "KnowledgeFSSourceSyncPolicyPayload",
            "KnowledgeFSSourceSyncPolicyResponse",
            "KnowledgeFSSourceWorkflowImportPayload",
            "KnowledgeFSSourceWorkflowCancelPayload",
            "KnowledgeFSSourceWorkflowResponse",
            "KnowledgeFSUploadPartPresignPayload",
            "KnowledgeFSUploadSessionAbortPayload",
            "KnowledgeFSUploadSessionCompletePayload",
            "KnowledgeFSUploadSessionCreatePayload",
            "KnowledgeFSPresignedUploadResponse",
            "KnowledgeFSUploadSessionCreateResponse",
            "KnowledgeFSUploadSessionMutationResponse",
            "KnowledgeFSGoldenQuestionBulkImportPayload",
            "KnowledgeFSGoldenQuestionBulkImportResponse",
            "KnowledgeFSGoldenQuestionEvidenceMatchPayload",
            "KnowledgeFSGoldenQuestionEvidenceMatchResponse",
        }.issubset(console_ns.models)
        assert {
            "KnowledgeFSQueryCreatePayload",
            "KnowledgeFSDocumentListResponse",
            "KnowledgeFSResearchTaskListResponse",
            "KnowledgeFSSettingsPayload",
            "KnowledgeFSSettingsResponse",
            "KnowledgeFSSourceCreatePayload",
            "KnowledgeFSSourceListResponse",
            "KnowledgeFSSourceResponse",
            "KnowledgeFSTraceListResponse",
        }.issubset(service_api_ns.models)
        assert console_ns.models["KnowledgeFSSpaceCreatePayload"].__schema__["additionalProperties"] is False
        query_capability_schema = console_ns.models["KnowledgeFSQueryStreamCapabilityResponse"].__schema__
        assert set(query_capability_schema["required"]) == {"expires_at", "operation_id", "token", "url"}
        assert query_capability_schema["properties"]["operation_id"]["const"] == "createQuery"

    @staticmethod
    def test_document_multimodal_manifest_console_bff_exposes_only_authorized_asset_urls(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        document_id = "018f0d60-7a49-7cc2-9c1b-5b36f18f2c44"
        manifest = _document_multimodal_manifest(
            object_key=(
                f"tenant-1/spaces/018f0d60-7a49-7cc2-9c1b-5b36f18f2c43/documents/{document_id}/assets/figure-1-full.png"
            )
        )
        facade = FakeComponent(get_document_multimodal_manifest=Recorder(manifest))
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        apply_config_overrides(monkeypatch, CONSOLE_API_URL="")
        app = Flask(__name__)

        with app.test_request_context():
            get = inspect.unwrap(console_resources.KnowledgeFSSpaceDocumentMultimodalManifestApi.get)
            response = get(
                console_resources.KnowledgeFSSpaceDocumentMultimodalManifestApi(),
                control_space_id="control-1",
                document_id=document_id,
            )

        item = response["items"][0]
        assert item["asset_url"] == (
            f"/console/api/knowledge-fs/spaces/control-1/documents/{document_id}/multimodal/figure%3A1/asset"
        )
        assert item["thumbnail_url"] == f"{item['asset_url']}?variant=thumbnail"
        assert item["parse_element_id"] == "parse-element-1"
        assert "objectKey" not in str(response)
        assert "sha256" not in str(response)
        assert facade.get_document_multimodal_manifest.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="control-1",
                document_id=document_id,
            )
        ]

    @staticmethod
    def test_document_multimodal_asset_console_bff_reauthorizes_and_streams_scoped_images(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        document_id = "018f0d60-7a49-7cc2-9c1b-5b36f18f2c44"
        object_key = (
            f"tenant-1/spaces/018f0d60-7a49-7cc2-9c1b-5b36f18f2c43/documents/{document_id}/assets/figure-1-full.png"
        )
        manifest = _document_multimodal_manifest(object_key=object_key)
        facade = FakeComponent(get_document_multimodal_manifest=Recorder(manifest))
        object_storage = FakeComponent(
            head_object=Recorder(
                KnowledgeFSObjectMetadata(
                    checksum_sha256_base64="checksum",
                    content_type="image/png",
                    key=object_key,
                    metadata={},
                    size_bytes=4,
                )
            )
        )
        download_service = FakeComponent(load_stream=Recorder(iter((b"im", b"age"))))
        download_service_factory = Recorder(download_service)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSObjectStorageService", lambda: object_storage)
        monkeypatch.setattr(console_resources, "KnowledgeFSDownloadService", download_service_factory)
        app = Flask(__name__)

        with app.test_request_context():
            get = inspect.unwrap(console_resources.KnowledgeFSSpaceDocumentMultimodalAssetApi.get)
            response = get(
                console_resources.KnowledgeFSSpaceDocumentMultimodalAssetApi(),
                control_space_id="control-1",
                document_id=document_id,
                item_id="figure:1",
            )

        assert b"".join(response.response) == b"image"
        assert response.content_type == "image/png"
        assert response.headers["Content-Disposition"] == "inline"
        assert response.headers["Content-Security-Policy"] == "default-src 'none'; sandbox"
        assert response.headers["X-Content-Type-Options"] == "nosniff"
        assert object_storage.head_object.calls == [invocation(key=object_key)]
        assert download_service_factory.calls == [invocation(object_storage=object_storage)]
        assert len(download_service.load_stream.calls) == 1

    @staticmethod
    def test_document_multimodal_asset_console_bff_rejects_cross_document_object_keys(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        document_id = "018f0d60-7a49-7cc2-9c1b-5b36f18f2c44"
        manifest = _document_multimodal_manifest(
            object_key=(
                "tenant-1/spaces/018f0d60-7a49-7cc2-9c1b-5b36f18f2c43/"
                "documents/018f0d60-7a49-7cc2-9c1b-5b36f18f2cff/assets/foreign.png"
            )
        )
        facade = FakeComponent(get_document_multimodal_manifest=Recorder(manifest))
        object_storage_factory = Recorder()
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        monkeypatch.setattr(console_resources, "KnowledgeFSObjectStorageService", object_storage_factory)
        app = Flask(__name__)
        get = inspect.unwrap(console_resources.KnowledgeFSSpaceDocumentMultimodalAssetApi.get)

        with app.test_request_context(), pytest.raises(NotFound):
            get(
                console_resources.KnowledgeFSSpaceDocumentMultimodalAssetApi(),
                control_space_id="control-1",
                document_id=document_id,
                item_id="figure:1",
            )

        assert object_storage_factory.calls == []

    @staticmethod
    def test_source_workflow_import_contract_is_discriminated_idempotent_and_accepted() -> None:
        import_schema = console_ns.models["KnowledgeFSSourceWorkflowImportPayload"].__schema__
        assert import_schema["discriminator"] == {
            "propertyName": "kind",
            "mapping": {
                "online-document-import": "#/components/schemas/KnowledgeFSOnlineDocumentWorkflowImportPayload",
                "online-drive-import": "#/components/schemas/KnowledgeFSOnlineDriveWorkflowImportPayload",
            },
        }
        assert import_schema["oneOf"] == [
            {"$ref": "#/components/schemas/KnowledgeFSOnlineDocumentWorkflowImportPayload"},
            {"$ref": "#/components/schemas/KnowledgeFSOnlineDriveWorkflowImportPayload"},
        ]

        api_doc = vars(console_resources.KnowledgeFSSpaceSourceWorkflowImportApi.post)["__apidoc__"]
        assert api_doc["params"]["Idempotency-Key"]["required"] is True
        assert api_doc["params"]["Idempotency-Key"]["minLength"] == 8
        assert api_doc["params"]["Idempotency-Key"]["maxLength"] == 255
        assert set(api_doc["responses"]) == {"202"}

    @staticmethod
    def test_small_file_console_bff_reads_only_through_facade_and_returns_no_capability_material(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        calls: list[dict[str, object]] = []

        class Facade:
            def upload_small_file(self, **kwargs: object) -> KnowledgeFSSmallFileUploadResponse:
                calls.append({name: value for name, value in kwargs.items() if name != "body_reader"})
                body_reader = kwargs["body_reader"]
                assert callable(body_reader)
                assert body_reader(8 * 1024 * 1024) == b"tiny"
                return KnowledgeFSSmallFileUploadResponse.model_validate(
                    {
                        "session": {
                            "compilationJobId": "compilation-1",
                            "completedAt": 2_000_000,
                            "documentAssetId": "asset-1",
                            "expectedSizeBytes": 4,
                            "expiresAt": 2_060_000,
                            "id": "session-1",
                            "mode": "small_fallback",
                            "status": "completed",
                        }
                    }
                )

        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: _FacadeRuntime(facade=Facade()))
        app = Flask(__name__)

        with app.test_request_context(
            method="POST",
            data={"file": (BytesIO(b"tiny"), "small.txt")},
            content_type="multipart/form-data",
        ):
            post = inspect.unwrap(console_resources.KnowledgeFSSpaceSmallFileUploadApi.post)
            response = post(console_resources.KnowledgeFSSpaceSmallFileUploadApi(), "control-1", "session-1")

        assert response["session"]["status"] == "completed"
        assert "token" not in str(response).lower()
        assert "url" not in str(response).lower()
        assert calls == [
            {
                "tenant_id": "tenant-1",
                "account_id": "account-1",
                "control_space_id": "control-1",
                "upload_session_id": "session-1",
            }
        ]

    @staticmethod
    def test_document_upload_console_bff_reads_only_through_facade_and_returns_accepted_response(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        calls: list[dict[str, object]] = []

        class Facade:
            def create_document(self, **kwargs: object) -> KnowledgeFSDocumentUploadAcceptedResponse:
                calls.append({name: value for name, value in kwargs.items() if name != "body_reader"})
                body_reader = kwargs["body_reader"]
                assert callable(body_reader)
                assert body_reader(15 * 1024 * 1024) == KnowledgeFSRemoteMultipartFile(
                    filename="notes.md",
                    content_type="text/markdown",
                    body=b"# Notes",
                )
                return KnowledgeFSDocumentUploadAcceptedResponse.model_validate(
                    {
                        "asset": {
                            "createdAt": "2030-01-01T00:00:00Z",
                            "filename": "notes.md",
                            "id": "asset-1",
                            "knowledgeSpaceId": "space-1",
                            "metadata": {},
                            "mimeType": "text/markdown",
                            "objectKey": "documents/asset-1/notes.md",
                            "parserStatus": "pending",
                            "sha256": "sha256",
                            "sizeBytes": 7,
                            "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",
                    }
                )

        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: _FacadeRuntime(facade=Facade()))
        app = Flask(__name__)

        with app.test_request_context(
            method="POST",
            data={"file": (BytesIO(b"# Notes"), "notes.md", "text/markdown")},
            content_type="multipart/form-data",
        ):
            post = inspect.unwrap(console_resources.KnowledgeFSSpaceDocumentsApi.post)
            response, status = post(console_resources.KnowledgeFSSpaceDocumentsApi(), "control-1")

        assert status == 202
        assert response["logical_document_id"] == "document-1"
        assert calls == [
            {
                "tenant_id": "tenant-1",
                "account_id": "account-1",
                "control_space_id": "control-1",
            }
        ]

    @staticmethod
    def test_staged_document_claim_passes_only_upload_id_to_the_admission_service(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        staged_uploads = FakeComponent(
            claim=Recorder(
                KnowledgeFSDocumentStagedUploadAcceptedResponse(
                    upload_id="staged-1",
                    document_asset_id="asset-1",
                    compilation_job_id="job-1",
                )
            )
        )
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_staged_uploads", lambda: staged_uploads)
        app = Flask(__name__)

        with app.test_request_context(method="POST", json={"upload_id": "staged-1"}):
            post = inspect.unwrap(console_resources.KnowledgeFSSpaceDocumentsApi.post)
            response, status = post(console_resources.KnowledgeFSSpaceDocumentsApi(), "control-1")

        assert status == 202
        assert response == {
            "status": "accepted",
            "upload_id": "staged-1",
            "document_asset_id": "asset-1",
            "compilation_job_id": "job-1",
        }
        assert len(staged_uploads.claim.calls) == 1
        claimed = narrowed(staged_uploads.claim.last_call.kwargs["payload"], KnowledgeFSDocumentStagedUploadPayload)
        assert claimed.upload_id == "staged-1"

    @staticmethod
    @pytest.mark.parametrize("file_size_limit_mb", [15, 50])
    def test_workspace_staging_upload_persists_before_space_creation(
        monkeypatch: pytest.MonkeyPatch,
        file_size_limit_mb: int,
    ) -> None:
        admission_events: list[str] = []

        class RecordingAdmission:
            active = False

            @contextmanager
            def admit(self, *, reserved_bytes: int) -> Generator[None]:
                admission_events.append(f"admit:{reserved_bytes}")
                self.active = True
                try:
                    yield
                finally:
                    self.active = False
                    admission_events.append("release")

        admission = RecordingAdmission()
        staged = KnowledgeFSStagedUploadResponse(
            id="staged-1",
            file_name="notes.md",
            content_type="text/markdown",
            size_bytes=7,
            status="uploaded",
            expires_at=datetime(2030, 1, 1, tzinfo=UTC),
        )

        def stage(**_: object) -> KnowledgeFSStagedUploadResponse:
            assert admission.active
            admission_events.append("stage")
            return staged

        staged_uploads = FakeComponent(stage=Recorder(effect=stage))
        account = _knowledge_fs_product_controllers_account()
        monkeypatch.setattr(console_resources, "current_account_with_tenant", lambda: (account, "tenant-1"))
        monkeypatch.setattr(console_resources, "_staged_uploads", lambda: staged_uploads)
        monkeypatch.setattr(console_resources, "DEFAULT_KNOWLEDGE_FS_BUFFERED_UPLOAD_ADMISSION", admission)
        monkeypatch.setattr(
            console_resources.FeatureService,
            "get_knowledge_file_size_limit",
            lambda _tenant_id: file_size_limit_mb,
        )
        app = Flask(__name__)

        with app.test_request_context(
            method="POST",
            data={"file": (BytesIO(b"# Notes"), "notes.md", "text/markdown")},
            content_type="multipart/form-data",
        ):
            post = inspect.unwrap(console_resources.KnowledgeFSStagedUploadsApi.post)
            response, status = post(console_resources.KnowledgeFSStagedUploadsApi())

        assert status == 201
        assert response["id"] == "staged-1"
        assert admission_events == [f"admit:{file_size_limit_mb * 1024 * 1024}", "stage", "release"]
        assert staged_uploads.stage.calls == [
            invocation(
                tenant_id="tenant-1",
                account=account,
                file_name="notes.md",
                content_type="text/markdown",
                body=b"# Notes",
                file_size_limit_mb=file_size_limit_mb,
            )
        ]

    @staticmethod
    def test_workspace_staging_zero_byte_plan_limit_returns_request_too_large_before_admission(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        class FailingAdmission:
            def admit(self, *, reserved_bytes: int) -> Never:
                _ = reserved_bytes
                raise AssertionError("a disabled upload limit must fail before admission")

        staged_uploads = FakeComponent(stage=Recorder())
        account = _knowledge_fs_product_controllers_account()
        monkeypatch.setattr(console_resources, "current_account_with_tenant", lambda: (account, "tenant-1"))
        monkeypatch.setattr(console_resources, "_staged_uploads", lambda: staged_uploads)
        monkeypatch.setattr(console_resources, "DEFAULT_KNOWLEDGE_FS_BUFFERED_UPLOAD_ADMISSION", FailingAdmission())
        monkeypatch.setattr(
            console_resources.FeatureService,
            "get_knowledge_file_size_limit",
            lambda _tenant_id: 0,
        )
        app = Flask(__name__)

        with app.test_request_context(
            method="POST",
            data={"file": (BytesIO(b"# Notes"), "notes.md", "text/markdown")},
            content_type="multipart/form-data",
        ):
            post = inspect.unwrap(console_resources.KnowledgeFSStagedUploadsApi.post)
            with pytest.raises(KnowledgeFSProductRequestRejectedError) as rejected:
                post(console_resources.KnowledgeFSStagedUploadsApi())

        assert rejected.value.status_code == 413
        assert staged_uploads.stage.calls == []

    @staticmethod
    def test_logical_document_delete_accepts_initial_row_version(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        calls: list[dict[str, object]] = []

        class Facade:
            def delete_logical_document(self, **kwargs: object) -> KnowledgeFSDurableDeletionAcceptedResponse:
                calls.append(kwargs)
                payload = kwargs["payload"]
                assert isinstance(payload, KnowledgeFSLogicalDocumentDeletePayload)
                assert payload.expected_revision == 0
                return KnowledgeFSDurableDeletionAcceptedResponse.model_validate(
                    {
                        "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": "logical_document",
                            "updatedAt": "2030-01-01T00:00:00Z",
                        },
                        "statusUrl": "/deletion-jobs/job-1",
                    }
                )

        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: _FacadeRuntime(facade=Facade()))
        app = Flask(__name__)

        with app.test_request_context(
            method="DELETE",
            json={"expectedRevision": 0},
            headers={"Idempotency-Key": "delete-logical-document-once"},
        ):
            delete = inspect.unwrap(console_resources.KnowledgeFSSpaceLogicalDocumentApi.delete)
            response, status = delete(
                console_resources.KnowledgeFSSpaceLogicalDocumentApi(),
                "control-1",
                "document-1",
            )

        assert status == 202
        assert response["job"]["target_type"] == "logical_document"
        assert len(calls) == 1
        assert {name: value for name, value in calls[0].items() if name != "payload"} == {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "control-1",
            "document_id": "document-1",
            "idempotency_key": "delete-logical-document-once",
        }

    @staticmethod
    def test_small_file_console_bff_maps_oversize_to_413() -> None:
        app = Flask(__name__)
        with app.test_request_context(
            method="POST",
            data={"file": (BytesIO(b"large"), "large.bin")},
            content_type="multipart/form-data",
        ):
            with pytest.raises(KnowledgeFSProductRequestRejectedError) as oversized:
                console_resources._read_small_file_body(4)
        assert oversized.value.status_code == 413

        @console_resources._knowledge_fs_errors
        def reject() -> Never:
            raise KnowledgeFSProductRequestRejectedError(status_code=413)

        with pytest.raises(KnowledgeFSRequestTooLargeHTTPError):
            reject()

    @staticmethod
    def test_console_knowledge_rate_limit_covers_every_write_download_and_retrieval_entrypoint() -> None:
        """Mirror the legacy dataset console: every mutating, download, or retrieval route is rate limited.

        Pure reads stay unlimited. The exemptions are workspace-level source previews (like legacy
        data source browsing), a staged-upload discard, the deprecated buffered query route that
        fails closed anyway, and the internal capability-token stream transport.
        """
        space = "/knowledge-fs/spaces/<string:control_space_id>"
        exempt_writes = {
            ("post", "/knowledge-fs/source-provider-preview"),
            ("post", "/knowledge-fs/source-provider-preview/jobs"),
            ("delete", "/knowledge-fs/source-provider-preview/jobs/<string:job_id>"),
            ("delete", "/knowledge-fs/uploads/<string:upload_id>"),
            ("post", f"{space}/queries"),
            ("post", "_QUERY_STREAM_PROXY_PATH"),
        }
        rate_limited_reads = {("get", f"{space}/logical-documents/<string:document_id>/download")}
        tree = ast.parse(
            Path(console_resources.__file__).read_text(encoding="utf-8"),
            filename=console_resources.__file__,
        )
        seen: set[tuple[str, str]] = set()

        for class_node in (node for node in tree.body if isinstance(node, ast.ClassDef)):
            routes = [
                ast.unparse(decorator.args[0]).strip("'\"")
                for decorator in class_node.decorator_list
                if isinstance(decorator, ast.Call)
                and isinstance(decorator.func, ast.Attribute)
                and decorator.func.attr == "route"
            ]
            if not routes:
                continue
            for method_node in (
                node
                for node in class_node.body
                if isinstance(node, ast.FunctionDef) and node.name in {"delete", "get", "patch", "post", "put"}
            ):
                key = (method_node.name, routes[0])
                seen.add(key)
                rate_limited = any(
                    isinstance(decorator, ast.Call)
                    and isinstance(decorator.func, ast.Name)
                    and decorator.func.id == "cloud_edition_billing_rate_limit_check"
                    and len(decorator.args) == 1
                    and isinstance(decorator.args[0], ast.Constant)
                    and decorator.args[0].value == "knowledge"
                    for decorator in method_node.decorator_list
                )
                expected = key in rate_limited_reads if method_node.name == "get" else key not in exempt_writes
                assert rate_limited == expected, f"{key} rate limited={rate_limited}, expected {expected}"

        assert exempt_writes <= seen
        assert rate_limited_reads <= seen

    @staticmethod
    def test_space_update_and_delete_publish_their_actual_http_status_contracts() -> None:
        patch_responses = vars(console_resources.KnowledgeFSSpaceApi.patch)["__apidoc__"]["responses"]
        delete_responses = vars(console_resources.KnowledgeFSSpaceApi.delete)["__apidoc__"]["responses"]

        assert set(patch_responses) == {"200"}
        assert set(delete_responses) == {"204"}

    @staticmethod
    def test_space_create_profile_intent_matches_the_exact_kfs_pending_configuration_shape() -> None:
        payload = KnowledgeFSSpaceCreatePayload.model_validate(
            {
                "name": "Technical space",
                "slug": "technical-space",
                "embedding": {
                    "pluginId": "langgenius/openai",
                    "provider": "openai",
                    "model": "text-embedding-3-small",
                },
                "retrieval": {
                    "defaultMode": "deep",
                    "reasoningModel": {
                        "pluginId": "langgenius/openai",
                        "provider": "openai",
                        "model": "gpt-4.1-mini",
                    },
                    "rerank": {
                        "enabled": True,
                        "model": {
                            "pluginId": "langgenius/cohere",
                            "provider": "cohere",
                            "model": "rerank-v3.5",
                        },
                    },
                    "scoreThreshold": {"enabled": True, "stage": "mode-final", "value": 0.6},
                    "topK": 20,
                },
            }
        )

        assert payload.embedding is not None
        assert payload.embedding is not None
        assert payload.embedding.model_dump(mode="json", by_alias=True) == {
            "pluginId": "langgenius/openai",
            "provider": "openai",
            "model": "text-embedding-3-small",
        }
        assert payload.retrieval is not None
        assert payload.retrieval is not None
        assert payload.retrieval.model_dump(mode="json", by_alias=True) == {
            "defaultMode": "deep",
            "reasoningModel": {
                "pluginId": "langgenius/openai",
                "provider": "openai",
                "model": "gpt-4.1-mini",
            },
            "rerank": {
                "enabled": True,
                "model": {
                    "pluginId": "langgenius/cohere",
                    "provider": "cohere",
                    "model": "rerank-v3.5",
                },
            },
            "scoreThreshold": {"enabled": True, "stage": "mode-final", "value": 0.6},
            "topK": 20,
        }

        with pytest.raises(ValueError, match="retrieval.defaultMode"):
            KnowledgeFSSpaceCreatePayload.model_validate(
                {
                    "name": "Invalid preset",
                    "slug": "invalid-preset",
                    "embedding": {"pluginId": "plugin", "provider": "provider", "model": "embedding"},
                    "retrieval": {
                        "defaultMode": "auto",
                        "reasoningModel": {"pluginId": "plugin", "provider": "provider", "model": "reasoning"},
                        "rerank": {
                            "enabled": True,
                            "model": {"pluginId": "plugin", "provider": "provider", "model": "rerank"},
                        },
                        "scoreThreshold": {"enabled": False, "stage": "mode-final"},
                        "topK": 10,
                    },
                }
            )

    @staticmethod
    def test_space_create_allows_deferred_model_setup_but_rejects_incomplete_fast_profile() -> None:
        payload = KnowledgeFSSpaceCreatePayload.model_validate(
            {
                "name": "Setup later",
                "slug": "setup-later",
            }
        )

        assert payload.embedding is None
        assert payload.retrieval is None

        with pytest.raises(ValueError, match="requires an embedding model"):
            KnowledgeFSSpaceCreatePayload.model_validate(
                {
                    "name": "Incomplete fast profile",
                    "slug": "incomplete-fast-profile",
                    "retrieval": {
                        "defaultMode": "fast",
                        "reasoningModel": {
                            "pluginId": "plugin",
                            "provider": "provider",
                            "model": "reasoning",
                        },
                        "rerank": {
                            "enabled": True,
                            "model": {"pluginId": "plugin", "provider": "provider", "model": "rerank"},
                        },
                        "scoreThreshold": {"enabled": False, "stage": "mode-final"},
                        "topK": 10,
                    },
                }
            )

    @staticmethod
    def test_jwks_http_resource_returns_only_public_keys(monkeypatch: pytest.MonkeyPatch) -> None:
        public_jwks = {
            "keys": [
                {"alg": "RS256", "e": "AQAB", "kid": "current", "kty": "RSA", "n": "modulus-1", "use": "sig"},
                {"alg": "RS256", "e": "AQAB", "kid": "previous", "kty": "RSA", "n": "modulus-2", "use": "sig"},
            ]
        }
        issuer = FakeComponent(public_jwks=Recorder(public_jwks))
        apply_config_overrides(
            monkeypatch,
            KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=True,
            KNOWLEDGE_FS_JWKS_CACHE_MAX_AGE_SECONDS=123,
        )
        monkeypatch.setattr(console_resources.session_factory, "get_session_maker", lambda: object())
        monkeypatch.setattr(console_resources, "create_configured_knowledge_fs_capability_issuer", lambda **_: issuer)
        app = Flask(__name__)

        with app.app_context():
            response = console_resources.KnowledgeFSJWKSApi().get()

        payload = response.get_json()
        assert payload == public_jwks
        assert response.headers["Cache-Control"] == "public, max-age=123, must-revalidate"
        assert not {"d", "p", "q", "dp", "dq", "qi"} & set().union(*(key.keys() for key in payload["keys"]))

    @staticmethod
    def test_service_profile_authorizes_the_dataset_key_for_the_route_space(monkeypatch: pytest.MonkeyPatch) -> None:
        profile = KnowledgeFSServiceApiProfile(
            tenant_id="tenant-1",
            control_space_id="control-2",
            api_token_id="token-1",
            principal_id="token-1",
            knowledge_space_id="space-1",
            knowledge_space_revision=1,
            membership_epoch=0,
            space_acl_epoch=0,
            external_access_epoch=0,
            content_policy_revision=0,
        )
        authorization = FakeComponent(authorize=Recorder(profile))
        runtime = FakeRuntime(service_api_authorization=authorization)
        monkeypatch.setattr(service_resources, "validate_and_get_api_token", Recorder(_dataset_api_token()))
        app = Flask(__name__)
        with app.test_request_context(headers={"Authorization": "Bearer dataset-test-key"}):
            result = service_resources._profile(
                runtime,  # type: ignore[arg-type]
                operation_id="listDocuments",
                control_space_id="control-2",
            )

        assert result is profile
        assert authorization.authorize.calls == [
            invocation(
                api_token_id="token-1",
                tenant_id="tenant-1",
                control_space_id="control-2",
            )
        ]

    @staticmethod
    def test_service_profile_applies_the_knowledge_rate_limit_before_authorizing(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        """Every KnowledgeFS service route shares the legacy dataset service API rate limit."""
        authorization = FakeComponent(authorize=Recorder())
        runtime = FakeRuntime(service_api_authorization=authorization)
        api_token = _dataset_api_token()
        monkeypatch.setattr(service_resources, "validate_and_get_api_token", Recorder(api_token))
        rate_limit = Recorder(raises=Forbidden("rate limited"))
        monkeypatch.setattr(service_resources, "check_knowledge_rate_limit", rate_limit)

        with pytest.raises(Forbidden, match="rate limited"):
            service_resources._profile(
                runtime,  # type: ignore[arg-type]
                operation_id="listDocuments",
                control_space_id="control-2",
            )

        assert rate_limit.calls == [invocation(api_token)]
        assert authorization.authorize.calls == []

    @staticmethod
    def test_service_profile_rejects_a_dataset_key_without_a_workspace(monkeypatch: pytest.MonkeyPatch) -> None:
        authorization = FakeComponent(authorize=Recorder())
        runtime = FakeRuntime(service_api_authorization=authorization)
        monkeypatch.setattr(
            service_resources, "validate_and_get_api_token", Recorder(_dataset_api_token(tenant_id=None))
        )

        with pytest.raises(KnowledgeFSServiceApiAuthorizationError, match="not workspace-scoped"):
            service_resources._profile(
                runtime,  # type: ignore[arg-type]
                operation_id="listDocuments",
                control_space_id="control-2",
            )

        assert authorization.authorize.calls == []

    @staticmethod
    def test_product_modules_do_not_import_dify_dataset_or_document_services() -> None:
        paths = [
            *(path for path in _API_ROOT.glob("services/knowledge_fs/*.py") if not path.name.startswith("upgrade_")),
            *_API_ROOT.glob("controllers/console/knowledge_fs/*.py"),
            *_API_ROOT.glob("controllers/service_api/knowledge_fs/*.py"),
        ]
        forbidden_modules = {
            "models.dataset",
            "services.dataset_service",
            "services.document_service",
            "controllers.console.datasets",
            "controllers.service_api.dataset",
        }

        for path in paths:
            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
            imported_modules = set()
            for node in ast.walk(tree):
                if not isinstance(node, ast.ImportFrom) or node.module is None:
                    continue
                # Native vector credentials share the legacy models.dataset module.
                # This bridge may read the tenant binding, never Dataset/Document data.
                if (
                    path == _API_ROOT / "services/knowledge_fs/vector_store.py"
                    and node.module == "models.dataset"
                    and {alias.name for alias in node.names} == {"TidbAuthBinding"}
                ):
                    continue
                imported_modules.add(node.module)
            assert not any(
                module == forbidden or module.startswith(f"{forbidden}.")
                for module in imported_modules
                for forbidden in forbidden_modules
            ), path

    @staticmethod
    def test_research_task_stream_url_binds_task_and_parent_space_without_token(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        apply_config_overrides(monkeypatch, CONSOLE_API_URL="https://dify.test")
        url = console_resources._research_task_events_url(
            task_id="task/one",
            knowledge_space_id="space one",
        )

        assert (
            url
            == "https://dify.test/console/api/knowledge-fs/research-tasks/task%2Fone/events?knowledgeSpaceId=space+one"
        )
        assert "token" not in url.lower()

    @staticmethod
    def test_query_stream_capability_issues_exact_space_grant_without_token_in_url(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        calls: list[dict[str, object]] = []

        class Broker:
            def issue_interactive(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
                calls.append(kwargs)
                return _issued_capability(token="query-capability", operation_id="createQuery")

        apply_config_overrides(monkeypatch, CONSOLE_API_URL="https://dify.test")
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(
            console_resources,
            "_console_services",
            lambda: _BrokerRuntime(broker=Broker()),
        )
        app = Flask(__name__)

        with app.test_request_context():
            post = inspect.unwrap(console_resources.KnowledgeFSSpaceQueryStreamCapabilityApi.post)
            response = post(console_resources.KnowledgeFSSpaceQueryStreamCapabilityApi(), "control-1")

        assert response == {
            "expires_at": "2030-01-01T00:00:00Z",
            "operation_id": "createQuery",
            "token": "query-capability",
            "url": "https://dify.test/console/api/knowledge-fs/query-stream",
        }
        assert calls == [
            {
                "account_id": "account-1",
                "control_space_id": "control-1",
                "operation_id": "createQuery",
                "tenant_id": "tenant-1",
            }
        ]
        assert "token" not in response["url"].lower()
        assert vars(console_resources.KnowledgeFSSpaceQueryStreamCapabilityApi.post)["__apidoc__"]["deprecated"] is True

    @staticmethod
    def test_query_admission_binds_validated_mode_to_resolved_kfs_space(monkeypatch: pytest.MonkeyPatch) -> None:
        calls: list[dict[str, object]] = []

        class Broker:
            def issue_interactive(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
                calls.append(kwargs)
                return _issued_capability(token="query-capability", operation_id="createQuery")

        apply_config_overrides(monkeypatch, CONSOLE_API_URL="https://dify.test")
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(
            console_resources,
            "_console_services",
            lambda: _BrokerRuntime(broker=Broker()),
        )
        app = Flask(__name__)

        with app.test_request_context(json={"query": "What changed?", "mode": "auto"}):
            post = inspect.unwrap(console_resources.KnowledgeFSSpaceQueryAdmissionApi.post)
            response = post(console_resources.KnowledgeFSSpaceQueryAdmissionApi(), "control-1")

        assert response["operation_id"] == "createQuery"
        assert response["trace_id"] == "trace-1"
        assert response["request"] == {
            "activeDocumentIds": [],
            "activeEntityIds": [],
            "knowledgeSpaceId": "space-1",
            "mode": "auto",
            "query": "What changed?",
        }
        assert response["url"] == "https://dify.test/console/api/knowledge-fs/query-stream"
        assert calls == [
            {
                "account_id": "account-1",
                "control_space_id": "control-1",
                "operation_id": "createQuery",
                "tenant_id": "tenant-1",
            }
        ]

    @staticmethod
    def test_console_query_stream_proxy_forwards_only_the_admitted_capability(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        closed: list[str] = []

        def close() -> None:
            closed.append("closed")

        facade = FakeComponent(
            stream_query=Recorder(
                KnowledgeFSRemoteSSEResponse(
                    status_code=200,
                    headers=(
                        ("content-type", "text/event-stream"),
                        ("x-query-run-id", "query-1"),
                    ),
                    chunks=iter((b"event: answer\n", b'data: {"answer":"ok"}\n\n')),
                    close=close,
                )
            )
        )
        monkeypatch.setattr(console_resources, "_console_services", lambda: FakeRuntime(facade=facade))
        app = Flask(__name__)

        with app.test_request_context(
            json={
                "activeDocumentIds": [],
                "activeEntityIds": [],
                "knowledgeSpaceId": "space-1",
                "mode": "fast",
                "query": "hello",
            },
            headers={
                "Authorization": "Bearer capability-token",
                "Cookie": "session=must-not-forward",
                "X-Trace-ID": "trace-1",
            },
        ):
            post = inspect.unwrap(console_resources.KnowledgeFSQueryStreamProxyApi.post)
            response = post(console_resources.KnowledgeFSQueryStreamProxyApi())

        assert response.status_code == 200
        assert response.headers["Content-Type"] == "text/event-stream"
        assert response.headers["X-Accel-Buffering"] == "no"
        assert b"".join(response.response) == b'event: answer\ndata: {"answer":"ok"}\n\n'
        assert closed == ["closed"]
        call = facade.stream_query.last_call.kwargs
        assert call["capability_token"] == "capability-token"
        assert call["trace_id"] == "trace-1"
        assert narrowed(call["payload"], KnowledgeFSAdmittedQueryRequest).knowledge_space_id == "space-1"
        assert set(call) == {"capability_token", "trace_id", "payload"}

    @staticmethod
    def test_service_query_stream_proxy_forwards_only_the_admitted_capability(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        closed: list[str] = []

        def close() -> None:
            closed.append("closed")

        facade = FakeComponent(
            stream_query=Recorder(
                KnowledgeFSRemoteSSEResponse(
                    status_code=200,
                    headers=(
                        ("content-type", "text/event-stream"),
                        ("x-query-run-id", "query-1"),
                    ),
                    chunks=iter((b"event: answer\n", b'data: {"answer":"ok"}\n\n')),
                    close=close,
                )
            )
        )
        monkeypatch.setattr(service_resources, "_runtime", lambda: FakeRuntime(facade=facade))
        app = Flask(__name__)

        with app.test_request_context(
            json={
                "activeDocumentIds": [],
                "activeEntityIds": [],
                "knowledgeSpaceId": "space-1",
                "mode": "fast",
                "query": "hello",
            },
            headers={
                "Authorization": "Bearer capability-token",
                "Cookie": "session=must-not-forward",
                "X-Trace-ID": "trace-1",
            },
        ):
            post = inspect.unwrap(service_resources.KnowledgeFSServiceQueryStreamProxyApi.post)
            response = post(service_resources.KnowledgeFSServiceQueryStreamProxyApi())

        assert response.status_code == 200
        assert response.headers["Content-Type"] == "text/event-stream"
        assert response.headers["X-Accel-Buffering"] == "no"
        assert b"".join(response.response) == b'event: answer\ndata: {"answer":"ok"}\n\n'
        assert closed == ["closed"]
        call = facade.stream_query.last_call.kwargs
        assert call["capability_token"] == "capability-token"
        assert call["trace_id"] == "trace-1"
        assert narrowed(call["payload"], KnowledgeFSAdmittedQueryRequest).knowledge_space_id == "space-1"
        assert set(call) == {"capability_token", "trace_id", "payload"}

    @staticmethod
    @pytest.mark.parametrize(
        ("headers", "error_type"),
        [
            ({"X-Trace-ID": "trace-1"}, service_resources.KnowledgeFSInvalidCredentialHTTPError),
            (
                {"Authorization": "Bearer capability-token"},
                service_resources.KnowledgeFSServiceInvalidRequestHTTPError,
            ),
        ],
    )
    def test_service_query_stream_proxy_rejects_invalid_internal_transport_headers(
        headers: dict[str, str],
        error_type: type[Exception],
    ) -> None:
        app = Flask(__name__)

        with app.test_request_context(headers=headers), pytest.raises(error_type):
            service_resources._stream_capability()

    @staticmethod
    def test_task_stream_capability_uses_broker(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        calls: list[dict[str, object]] = []

        class Broker:
            def issue_interactive(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
                calls.append(kwargs)
                return _issued_capability(token="direct-capability", operation_id="streamResearchTask")

        runtime = _BrokerRuntime(broker=Broker())
        apply_config_overrides(monkeypatch, CONSOLE_API_URL="https://dify.test")
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        app = Flask(__name__)

        with app.test_request_context(json={"control_space_id": "control-1"}):
            stream_post = inspect.unwrap(console_resources.KnowledgeFSTaskStreamCapabilityApi.post)
            stream_response = stream_post(console_resources.KnowledgeFSTaskStreamCapabilityApi(), "task-1")

        assert stream_response["operation_id"] == "streamResearchTask"
        assert calls == [
            {
                "tenant_id": "tenant-1",
                "account_id": "account-1",
                "control_space_id": "control-1",
                "operation_id": "streamResearchTask",
                "resource_id": "task-1",
            },
        ]

    @staticmethod
    def test_service_query_admission_uses_broker(monkeypatch: pytest.MonkeyPatch) -> None:
        calls: list[dict[str, object]] = []
        profile = _service_profile("control-1")
        authorization = FakeComponent(authorize=Recorder(profile))

        class Broker:
            def issue_service(self, **kwargs: object) -> KnowledgeFSIssuedProductCapability:
                calls.append(kwargs)
                return _issued_capability(token="service-capability", operation_id="createQuery")

        @dataclass(frozen=True)
        class ServiceRuntime:
            service_api_authorization: FakeComponent
            broker: Broker

        runtime = ServiceRuntime(service_api_authorization=authorization, broker=Broker())
        monkeypatch.setattr(service_resources, "validate_and_get_api_token", Recorder(_dataset_api_token()))
        apply_config_overrides(monkeypatch, SERVICE_API_URL="https://api.dify.test")
        monkeypatch.setattr(service_resources, "_runtime", lambda: runtime)
        app = Flask(__name__)

        with app.test_request_context(
            json={"query": "What changed?", "mode": "fast"},
            headers={"Authorization": "Bearer dataset-test-key"},
        ):
            post = inspect.unwrap(service_resources.KnowledgeFSServiceQueryAdmissionApi.post)
            response = post(service_resources.KnowledgeFSServiceQueryAdmissionApi(), "control-1")

        assert response["operation_id"] == "createQuery"
        assert response["trace_id"] == "trace-1"
        assert response["request"]["knowledgeSpaceId"] == "space-1"
        assert response["url"] == "https://api.dify.test/v1/knowledge-fs/query-stream"
        assert authorization.authorize.calls == [
            invocation(
                api_token_id="token-1",
                tenant_id="tenant-1",
                control_space_id="control-1",
            )
        ]
        assert calls == [{"profile": profile, "operation_id": "createQuery"}]

    @staticmethod
    @pytest.mark.parametrize(
        ("raised", "expected"),
        [
            # An unknown or wrong-kind key is an invalid credential (401).
            (
                KnowledgeFSServiceApiAuthorizationError("bad key"),
                service_resources.KnowledgeFSInvalidCredentialHTTPError,
            ),
            # A real key bound to other knowledge bases is out of scope for this space (403).
            (
                KnowledgeFSServiceApiScopeError("out of scope"),
                service_resources.KnowledgeFSServiceAccessDeniedHTTPError,
            ),
        ],
    )
    def test_service_api_errors_distinguish_unknown_key_from_out_of_scope_key(
        raised: Exception,
        expected: type[Exception],
    ) -> None:
        @service_resources._service_api_errors
        def view() -> None:
            raise raised

        with pytest.raises(expected):
            view()

    @staticmethod
    def test_space_create_member_schema_requires_viewer_role() -> None:
        payload_schema = console_ns.models["KnowledgeFSSpaceCreatePayload"].__schema__
        member_schema = console_ns.models["KnowledgeFSSpaceCreateMemberPayload"].__schema__

        assert payload_schema["properties"]["members"]["maxItems"] == 1_000
        assert member_schema["properties"]["role"]["const"] == "viewer"
        assert set(member_schema["required"]) == {"account_id", "role"}
        assert member_schema["additionalProperties"] is False

    @staticmethod
    def test_space_create_initial_access_idempotency_conflict_returns_409() -> None:
        @console_resources._knowledge_fs_errors
        def conflicting_creation() -> None:
            raise KnowledgeFSControlSpaceIntentConflictError("different initial access")

        with pytest.raises(KnowledgeFSConflictHTTPError) as exc:
            conflicting_creation()

        assert exc.value.code == 409


_RAW_RESULT = object()


def source_response(**overrides: object) -> KnowledgeFSSourceResponse:
    return KnowledgeFSSourceResponse.model_validate(
        {
            "id": "source-1",
            "created_at": datetime(2026, 1, 1, tzinfo=UTC),
            "updated_at": datetime(2026, 1, 1, tzinfo=UTC),
            "knowledge_space_id": "space-1",
            "name": "Source",
            "permission_scope": [],
            "status": "active",
            "metadata": {},
            "type": "web",
            "uri": "https://example.com",
            "version": 1,
            **overrides,
        }
    )


def sync_policy_response(revision: int) -> KnowledgeFSSourceSyncPolicyResponse:
    return KnowledgeFSSourceSyncPolicyResponse.model_validate(
        {
            "created_at": datetime(2026, 1, 1, tzinfo=UTC),
            "enabled": True,
            "expected_source_version": 1,
            "id": "policy-1",
            "knowledge_space_id": "space-1",
            "mode": "interval",
            "revision": revision,
            "source_id": "source-1",
            "updated_at": datetime(2026, 1, 1, tzinfo=UTC),
        }
    )


def issued_capability() -> KnowledgeFSIssuedProductCapability:
    return KnowledgeFSIssuedProductCapability(
        token="capability-token",
        expires_at=datetime(2026, 7, 21, tzinfo=UTC),
        operation_id="createQuery",
        knowledge_space_id="knowledge-space-1",
        knowledge_space_revision=1,
        trace_id="trace-1",
    )


def _knowledge_fs_resource_delegation_account(account_id: str) -> Account:
    account = Account(name="Test User", email="[email protected]")
    account.id = account_id
    return account


@dataclass(frozen=True)
class _SettingsUpdateResult:
    """The only field the settings route reads before dumping the facade result."""

    migration: None = None


@dataclass(frozen=True)
class _MembersPayload:
    members: tuple[str, ...]
    query_images: list[str] = field(default_factory=list)


def _invoke[R](resource_type: type[Resource], handler: Callable[..., R], *args: object) -> R:
    return unwrap(handler)(resource_type(), *args)


# Each case names the public resource, HTTP method, route arguments, and the one
# application boundary that owns the operation. Route-specific identifiers are
# asserted below so accidental delegation to a sibling resource is observable.
_CONSOLE_DELEGATION_CASES = (
    (
        console_resources.KnowledgeFSSpacesApi,
        console_resources.KnowledgeFSSpacesApi.get,
        (),
        "application",
        "list_spaces",
        dict[str, object](),
    ),
    (
        console_resources.KnowledgeFSSpacesApi,
        console_resources.KnowledgeFSSpacesApi.post,
        (
            RequestContext(
                request_id="request-1", trace_id=None, account_id="account-1", active_workspace_id="tenant-1"
            ),
        ),
        "application",
        "create_space",
        dict[str, object](),
    ),
    (
        console_resources.KnowledgeFSSpaceApi,
        console_resources.KnowledgeFSSpaceApi.get,
        ("space-1",),
        "application",
        "get_space",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceApi,
        console_resources.KnowledgeFSSpaceApi.patch,
        ("space-1",),
        "application",
        "update_space",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceApi,
        console_resources.KnowledgeFSSpaceApi.delete,
        ("space-1",),
        "application",
        "delete_space",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpacePermissionsApi,
        console_resources.KnowledgeFSSpacePermissionsApi.get,
        ("space-1",),
        "control_plane",
        "list_permissions",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceMembersApi,
        console_resources.KnowledgeFSSpaceMembersApi.put,
        ("space-1",),
        "control_plane",
        "replace_members",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceExternalAccessApi,
        console_resources.KnowledgeFSSpaceExternalAccessApi.get,
        ("space-1",),
        "control_plane",
        "get_external_access",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceExternalAccessApi,
        console_resources.KnowledgeFSSpaceExternalAccessApi.put,
        ("space-1",),
        "control_plane",
        "update_external_access",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceAppBindingsApi,
        console_resources.KnowledgeFSSpaceAppBindingsApi.get,
        ("space-1",),
        "app_bindings",
        "list",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceAppBindingsApi,
        console_resources.KnowledgeFSSpaceAppBindingsApi.put,
        ("space-1",),
        "app_bindings",
        "upsert",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceAppBindingApi,
        console_resources.KnowledgeFSSpaceAppBindingApi.delete,
        ("space-1", KnowledgeFSAppSpaceJoinType.AGENT.value, "app-1"),
        "app_bindings",
        "revoke",
        {
            "control_space_id": "space-1",
            "app_id": "app-1",
            "caller_kind": KnowledgeFSAppSpaceJoinType.AGENT,
        },
    ),
    (
        console_resources.KnowledgeFSSpaceSettingsApi,
        console_resources.KnowledgeFSSpaceSettingsApi.get,
        ("space-1",),
        "facade",
        "get_settings",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSettingsApi,
        console_resources.KnowledgeFSSpaceSettingsApi.patch,
        ("space-1",),
        "facade",
        "update_settings",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceOverviewQueryOutcomesApi,
        console_resources.KnowledgeFSSpaceOverviewQueryOutcomesApi.get,
        ("space-1",),
        "facade",
        "get_overview_query_outcomes",
        {"control_space_id": "space-1", "window": "24h"},
    ),
    (
        console_resources.KnowledgeFSSpaceOverviewInventoryApi,
        console_resources.KnowledgeFSSpaceOverviewInventoryApi.get,
        ("space-1",),
        "facade",
        "get_overview_inventory",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceOverviewAttentionApi,
        console_resources.KnowledgeFSSpaceOverviewAttentionApi.get,
        ("space-1",),
        "facade",
        "list_overview_attention",
        {"control_space_id": "space-1", "include_dismissed": False, "limit": 50},
    ),
    (
        console_resources.KnowledgeFSSpaceOverviewActivityApi,
        console_resources.KnowledgeFSSpaceOverviewActivityApi.get,
        ("space-1",),
        "facade",
        "list_overview_activity",
        {
            "control_space_id": "space-1",
            "action": None,
            "actor_id": None,
            "actor_type": None,
            "cursor": None,
            "from_at": None,
            "limit": 50,
            "resource_type": None,
            "result": None,
            "to_at": None,
        },
    ),
    (
        console_resources.KnowledgeFSSpaceOverviewHealthApi,
        console_resources.KnowledgeFSSpaceOverviewHealthApi.get,
        ("space-1",),
        "facade",
        "get_overview_health",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentsApi,
        console_resources.KnowledgeFSSpaceDocumentsApi.get,
        ("space-1",),
        "facade",
        "list_documents",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceBulkDocumentsApi,
        console_resources.KnowledgeFSSpaceBulkDocumentsApi.delete,
        ("space-1",),
        "facade",
        "bulk_delete_documents",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentReindexApi,
        console_resources.KnowledgeFSSpaceDocumentReindexApi.post,
        ("space-1",),
        "facade",
        "reindex_documents",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentApi,
        console_resources.KnowledgeFSSpaceDocumentApi.get,
        ("space-1", "document-1"),
        "facade",
        "get_document",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentApi,
        console_resources.KnowledgeFSSpaceDocumentApi.patch,
        ("space-1", "document-1"),
        "facade",
        "update_document_metadata",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceMetadataApi,
        console_resources.KnowledgeFSSpaceMetadataApi.get,
        ("space-1",),
        "facade",
        "list_metadata_fields",
        {"control_space_id": "space-1", "cursor": None, "limit": 100},
    ),
    (
        console_resources.KnowledgeFSSpaceMetadataApi,
        console_resources.KnowledgeFSSpaceMetadataApi.post,
        ("space-1",),
        "facade",
        "create_metadata_field",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceMetadataFieldApi,
        console_resources.KnowledgeFSSpaceMetadataFieldApi.patch,
        ("space-1", "field-1"),
        "facade",
        "update_metadata_field",
        {"control_space_id": "space-1", "field_id": "field-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentApi,
        console_resources.KnowledgeFSSpaceDocumentApi.delete,
        ("space-1", "document-1"),
        "facade",
        "delete_document",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceLogicalDocumentApi,
        console_resources.KnowledgeFSSpaceLogicalDocumentApi.delete,
        ("space-1", "document-1"),
        "facade",
        "delete_logical_document",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentOutlineApi,
        console_resources.KnowledgeFSSpaceDocumentOutlineApi.get,
        ("space-1", "document-1"),
        "facade",
        "get_document_outline",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentRevisionsApi,
        console_resources.KnowledgeFSSpaceDocumentRevisionsApi.get,
        ("space-1", "document-1"),
        "facade",
        "list_document_revisions",
        {"control_space_id": "space-1", "document_id": "document-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentChunksApi,
        console_resources.KnowledgeFSSpaceDocumentChunksApi.get,
        ("space-1", "document-1", 3),
        "facade",
        "list_document_chunks",
        {"control_space_id": "space-1", "document_id": "document-1", "revision": 3},
    ),
    (
        console_resources.KnowledgeFSSpaceDocumentChunkApi,
        console_resources.KnowledgeFSSpaceDocumentChunkApi.get,
        ("space-1", "document-1", 3, "chunk-1"),
        "facade",
        "get_document_chunk",
        {
            "control_space_id": "space-1",
            "document_id": "document-1",
            "revision": 3,
            "chunk_id": "chunk-1",
        },
    ),
    (
        console_resources.KnowledgeFSSpaceCompilationJobApi,
        console_resources.KnowledgeFSSpaceCompilationJobApi.get,
        ("space-1", "job-1"),
        "facade",
        "get_compilation_job",
        {"control_space_id": "space-1", "job_id": "job-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceCompilationJobApi,
        console_resources.KnowledgeFSSpaceCompilationJobApi.delete,
        ("space-1", "job-1"),
        "facade",
        "cancel_compilation_job",
        {"control_space_id": "space-1", "job_id": "job-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceCompilationJobRetryApi,
        console_resources.KnowledgeFSSpaceCompilationJobRetryApi.post,
        ("space-1", "job-1"),
        "facade",
        "retry_compilation_job",
        {"control_space_id": "space-1", "job_id": "job-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceBulkJobApi,
        console_resources.KnowledgeFSSpaceBulkJobApi.get,
        ("space-1", "job-1"),
        "facade",
        "get_bulk_job",
        {"control_space_id": "space-1", "job_id": "job-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceBackgroundTasksApi,
        console_resources.KnowledgeFSSpaceBackgroundTasksApi.get,
        ("space-1",),
        "facade",
        "list_background_tasks",
        {"control_space_id": "space-1", "cursor": None, "limit": 50},
    ),
    (
        console_resources.KnowledgeFSSpaceBackgroundTaskCancelApi,
        console_resources.KnowledgeFSSpaceBackgroundTaskCancelApi.post,
        ("space-1", "source", "task-1"),
        "facade",
        "cancel_background_task",
        {"control_space_id": "space-1", "task_kind": "source", "task_id": "task-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceBackgroundTaskRetryApi,
        console_resources.KnowledgeFSSpaceBackgroundTaskRetryApi.post,
        ("space-1", "document_bulk", "task-1"),
        "facade",
        "retry_background_task",
        {
            "control_space_id": "space-1",
            "task_kind": "document_bulk",
            "task_id": "task-1",
        },
    ),
    (
        console_resources.KnowledgeFSSpaceSourcesApi,
        console_resources.KnowledgeFSSpaceSourcesApi.get,
        ("space-1",),
        "facade",
        "list_sources",
        {"control_space_id": "space-1", "limit": 50},
    ),
    (
        console_resources.KnowledgeFSSpaceSourcesApi,
        console_resources.KnowledgeFSSpaceSourcesApi.post,
        ("space-1",),
        "facade",
        "create_source",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceApi,
        console_resources.KnowledgeFSSpaceSourceApi.get,
        ("space-1", "source-1"),
        "facade",
        "get_source",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceApi,
        console_resources.KnowledgeFSSpaceSourceApi.patch,
        ("space-1", "source-1"),
        "facade",
        "update_source",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceApi,
        console_resources.KnowledgeFSSpaceSourceApi.delete,
        ("space-1", "source-1"),
        "facade",
        "delete_source",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceTestApi,
        console_resources.KnowledgeFSSpaceSourceTestApi.post,
        ("space-1", "source-1"),
        "facade",
        "test_source",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceSyncApi,
        console_resources.KnowledgeFSSpaceSourceSyncApi.post,
        ("space-1", "source-1"),
        "facade",
        "sync_source",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceWorkflowImportApi,
        console_resources.KnowledgeFSSpaceSourceWorkflowImportApi.post,
        ("space-1", "source-1"),
        "facade",
        "import_source_workflow",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourcePagesApi,
        console_resources.KnowledgeFSSpaceSourcePagesApi.get,
        ("space-1", "source-1"),
        "facade",
        "list_source_pages",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourcePageImportApi,
        console_resources.KnowledgeFSSpaceSourcePageImportApi.post,
        ("space-1", "source-1"),
        "facade",
        "import_source_pages",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceFilesApi,
        console_resources.KnowledgeFSSpaceSourceFilesApi.get,
        ("space-1", "source-1"),
        "facade",
        "list_source_files",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSourceFileImportApi,
        console_resources.KnowledgeFSSpaceSourceFileImportApi.post,
        ("space-1", "source-1"),
        "facade",
        "import_source_files",
        {"control_space_id": "space-1", "source_id": "source-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTasksApi,
        console_resources.KnowledgeFSSpaceResearchTasksApi.get,
        ("space-1",),
        "facade",
        "list_research_tasks",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTasksApi,
        console_resources.KnowledgeFSSpaceResearchTasksApi.post,
        ("space-1",),
        "facade",
        "create_research_task",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTaskPlanApi,
        console_resources.KnowledgeFSSpaceResearchTaskPlanApi.post,
        ("space-1",),
        "facade",
        "plan_research_task",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTaskApi,
        console_resources.KnowledgeFSSpaceResearchTaskApi.get,
        ("space-1", "task-1"),
        "facade",
        "get_research_task",
        {"control_space_id": "space-1", "task_id": "task-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTaskApi,
        console_resources.KnowledgeFSSpaceResearchTaskApi.delete,
        ("space-1", "task-1"),
        "facade",
        "cancel_research_task",
        {"control_space_id": "space-1", "task_id": "task-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceResearchTaskPartialsApi,
        console_resources.KnowledgeFSSpaceResearchTaskPartialsApi.get,
        ("space-1", "task-1"),
        "facade",
        "list_research_task_partials",
        {"control_space_id": "space-1", "task_id": "task-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceTracesApi,
        console_resources.KnowledgeFSSpaceTracesApi.get,
        ("space-1",),
        "facade",
        "list_traces",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceTraceApi,
        console_resources.KnowledgeFSSpaceTraceApi.get,
        ("space-1", "trace-1"),
        "facade",
        "get_trace",
        {"control_space_id": "space-1", "trace_id": "trace-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceTraceEvidenceApi,
        console_resources.KnowledgeFSSpaceTraceEvidenceApi.get,
        ("space-1", "trace-1"),
        "facade",
        "list_trace_entries",
        {"control_space_id": "space-1", "trace_id": "trace-1", "kind": "evidence"},
    ),
    (
        console_resources.KnowledgeFSSpaceTraceConflictsApi,
        console_resources.KnowledgeFSSpaceTraceConflictsApi.get,
        ("space-1", "trace-1"),
        "facade",
        "list_trace_entries",
        {"control_space_id": "space-1", "trace_id": "trace-1", "kind": "conflicts"},
    ),
    (
        console_resources.KnowledgeFSSpaceTraceMissingApi,
        console_resources.KnowledgeFSSpaceTraceMissingApi.get,
        ("space-1", "trace-1"),
        "facade",
        "list_trace_entries",
        {"control_space_id": "space-1", "trace_id": "trace-1", "kind": "missing"},
    ),
    (
        console_resources.KnowledgeFSSpaceUploadSessionsApi,
        console_resources.KnowledgeFSSpaceUploadSessionsApi.post,
        ("space-1",),
        "facade",
        "create_upload_session",
        {"control_space_id": "space-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceUploadSessionPartPresignApi,
        console_resources.KnowledgeFSSpaceUploadSessionPartPresignApi.post,
        ("space-1", "session-1", 3),
        "facade",
        "presign_upload_session_part",
        {"control_space_id": "space-1", "upload_session_id": "session-1", "part_number": 3},
    ),
    (
        console_resources.KnowledgeFSSpaceUploadSessionCompleteApi,
        console_resources.KnowledgeFSSpaceUploadSessionCompleteApi.post,
        ("space-1", "session-1"),
        "facade",
        "complete_upload_session",
        {"control_space_id": "space-1", "upload_session_id": "session-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceUploadSessionAbortApi,
        console_resources.KnowledgeFSSpaceUploadSessionAbortApi.post,
        ("space-1", "session-1"),
        "facade",
        "abort_upload_session",
        {"control_space_id": "space-1", "upload_session_id": "session-1"},
    ),
    (
        console_resources.KnowledgeFSSpaceSmallFileUploadApi,
        console_resources.KnowledgeFSSpaceSmallFileUploadApi.post,
        ("space-1", "session-1"),
        "facade",
        "upload_small_file",
        {"control_space_id": "space-1", "upload_session_id": "session-1"},
    ),
)


_SERVICE_DELEGATION_CASES = (
    (
        service_resources.KnowledgeFSServiceBulkDocumentsApi,
        service_resources.KnowledgeFSServiceBulkDocumentsApi.delete,
        ("space-1",),
        "bulkDeleteDocuments",
        dict[str, object](),
    ),
    (
        service_resources.KnowledgeFSServiceDocumentReindexApi,
        service_resources.KnowledgeFSServiceDocumentReindexApi.post,
        ("space-1",),
        "reindexDocuments",
        dict[str, object](),
    ),
    (
        service_resources.KnowledgeFSServiceDocumentApi,
        service_resources.KnowledgeFSServiceDocumentApi.get,
        ("space-1", "document-1"),
        "getDocument",
        {"resource_id": "document-1", "path_parameters": (("documentId", "document-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceDocumentApi,
        service_resources.KnowledgeFSServiceDocumentApi.patch,
        ("space-1", "document-1"),
        "updateDocumentMetadata",
        {"resource_id": "document-1", "path_parameters": (("documentId", "document-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceDocumentApi,
        service_resources.KnowledgeFSServiceDocumentApi.delete,
        ("space-1", "document-1"),
        "deleteDocument",
        {"resource_id": "document-1", "path_parameters": (("documentId", "document-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceDocumentOutlineApi,
        service_resources.KnowledgeFSServiceDocumentOutlineApi.get,
        ("space-1", "document-1"),
        "getDocumentOutline",
        {"resource_id": "document-1", "path_parameters": (("documentId", "document-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceDocumentRevisionsApi,
        service_resources.KnowledgeFSServiceDocumentRevisionsApi.get,
        ("space-1", "document-1"),
        "listDocumentRevisions",
        {"resource_id": "document-1", "path_parameters": (("documentId", "document-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceDocumentChunksApi,
        service_resources.KnowledgeFSServiceDocumentChunksApi.get,
        ("space-1", "document-1", 3),
        "listDocumentChunks",
        {
            "resource_id": "document-1",
            "path_parameters": (("documentId", "document-1"), ("revision", "3")),
        },
    ),
    (
        service_resources.KnowledgeFSServiceDocumentChunkApi,
        service_resources.KnowledgeFSServiceDocumentChunkApi.get,
        ("space-1", "document-1", 3, "chunk-1"),
        "getDocumentChunk",
        {
            "resource_id": "document-1",
            "path_parameters": (("documentId", "document-1"), ("revision", "3"), ("chunkId", "chunk-1")),
        },
    ),
    (
        service_resources.KnowledgeFSServiceCompilationJobApi,
        service_resources.KnowledgeFSServiceCompilationJobApi.get,
        ("space-1", "job-1"),
        "getCompilationJob",
        {"resource_id": "job-1"},
    ),
    (
        service_resources.KnowledgeFSServiceCompilationJobApi,
        service_resources.KnowledgeFSServiceCompilationJobApi.delete,
        ("space-1", "job-1"),
        "cancelCompilationJob",
        {"resource_id": "job-1"},
    ),
    (
        service_resources.KnowledgeFSServiceCompilationJobRetryApi,
        service_resources.KnowledgeFSServiceCompilationJobRetryApi.post,
        ("space-1", "job-1"),
        "retryCompilationJob",
        {"resource_id": "job-1"},
    ),
    (
        service_resources.KnowledgeFSServiceBulkJobApi,
        service_resources.KnowledgeFSServiceBulkJobApi.get,
        ("space-1", "job-1"),
        "getBulkJob",
        {"resource_id": "job-1"},
    ),
    (
        service_resources.KnowledgeFSServiceSourceApi,
        service_resources.KnowledgeFSServiceSourceApi.get,
        ("space-1", "source-1"),
        "getSource",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceApi,
        service_resources.KnowledgeFSServiceSourceApi.patch,
        ("space-1", "source-1"),
        "updateSource",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceApi,
        service_resources.KnowledgeFSServiceSourceApi.delete,
        ("space-1", "source-1"),
        "deleteSource",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceTestApi,
        service_resources.KnowledgeFSServiceSourceTestApi.post,
        ("space-1", "source-1"),
        "testSource",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceCrawlApi,
        service_resources.KnowledgeFSServiceSourceCrawlApi.post,
        ("space-1", "source-1"),
        "previewSourceCrawl",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourcePagesApi,
        service_resources.KnowledgeFSServiceSourcePagesApi.get,
        ("space-1", "source-1"),
        "listSourcePages",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourcePageImportApi,
        service_resources.KnowledgeFSServiceSourcePageImportApi.post,
        ("space-1", "source-1"),
        "importSourceWorkflow",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceFilesApi,
        service_resources.KnowledgeFSServiceSourceFilesApi.get,
        ("space-1", "source-1"),
        "listSourceFiles",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceSourceFileImportApi,
        service_resources.KnowledgeFSServiceSourceFileImportApi.post,
        ("space-1", "source-1"),
        "importSourceWorkflow",
        {"resource_id": "source-1", "path_parameters": (("sourceId", "source-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceResearchTasksApi,
        service_resources.KnowledgeFSServiceResearchTasksApi.post,
        ("space-1",),
        "createResearchTask",
        {"bind_space_in_body": True},
    ),
    (
        service_resources.KnowledgeFSServiceResearchTaskPlanApi,
        service_resources.KnowledgeFSServiceResearchTaskPlanApi.post,
        ("space-1",),
        "planResearchTask",
        {"bind_space_in_body": True},
    ),
    (
        service_resources.KnowledgeFSServiceResearchTaskApi,
        service_resources.KnowledgeFSServiceResearchTaskApi.get,
        ("space-1", "task-1"),
        "getResearchTask",
        {"resource_id": "task-1"},
    ),
    (
        service_resources.KnowledgeFSServiceResearchTaskApi,
        service_resources.KnowledgeFSServiceResearchTaskApi.delete,
        ("space-1", "task-1"),
        "cancelResearchTask",
        {"resource_id": "task-1"},
    ),
    (
        service_resources.KnowledgeFSServiceResearchTaskPartialsApi,
        service_resources.KnowledgeFSServiceResearchTaskPartialsApi.get,
        ("space-1", "task-1"),
        "listResearchTaskPartials",
        {"resource_id": "task-1"},
    ),
    (
        service_resources.KnowledgeFSServiceTraceApi,
        service_resources.KnowledgeFSServiceTraceApi.get,
        ("space-1", "trace-1"),
        "getTrace",
        {"resource_id": "trace-1", "path_parameters": (("traceId", "trace-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceTraceEvidenceApi,
        service_resources.KnowledgeFSServiceTraceEvidenceApi.get,
        ("space-1", "trace-1"),
        "listTraceEvidence",
        {"resource_id": "trace-1", "path_parameters": (("traceId", "trace-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceTraceConflictsApi,
        service_resources.KnowledgeFSServiceTraceConflictsApi.get,
        ("space-1", "trace-1"),
        "listTraceConflicts",
        {"resource_id": "trace-1", "path_parameters": (("traceId", "trace-1"),)},
    ),
    (
        service_resources.KnowledgeFSServiceTraceMissingApi,
        service_resources.KnowledgeFSServiceTraceMissingApi.get,
        ("space-1", "trace-1"),
        "listTraceMissing",
        {"resource_id": "trace-1", "path_parameters": (("traceId", "trace-1"),)},
    ),
)


class TestKnowledgeFsResourceDelegationCases:
    @staticmethod
    @pytest.fixture(autouse=True)
    def _enabled_knowledge_fs(config_overrides: Callable[..., None]) -> None:
        config_overrides(DEPLOYMENT_EDITION=DeploymentEdition.CLOUD, KNOWLEDGE_FS_ENABLED=True)

    @staticmethod
    @pytest.mark.parametrize(
        ("class_name", "method_name", "route_args", "component_name", "delegate_name", "expected_fields"),
        _CONSOLE_DELEGATION_CASES,
    )
    def test_console_resources_delegate_one_tenant_scoped_product_operation(
        monkeypatch: pytest.MonkeyPatch,
        class_name: type[Resource],
        method_name: Callable[..., object],
        route_args: tuple[object, ...],
        component_name: str,
        delegate_name: str,
        expected_fields: dict[str, object],
    ) -> None:
        payload = (
            KnowledgeFSSourceUpdatePayload(name="Renamed")
            if class_name.__name__ == "KnowledgeFSSpaceSourceApi" and method_name.__name__ == "patch"
            else _MembersPayload(members=("member-1",))
        )
        delegate = Recorder(_RAW_RESULT)
        components = {name: FakeComponent() for name in ("application", "control_plane", "app_bindings", "facade")}
        components[component_name] = FakeComponent(**{delegate_name: delegate})
        runtime = FakeRuntime(
            application=components["application"],
            control_plane=components["control_plane"],
            app_bindings=components["app_bindings"],
            facade=components["facade"],
        )
        dump_response = Recorder(effect=lambda schema, raw: (schema.__name__, raw))
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(console_resources, "_idempotency_key", lambda: "idempotency-1")
        monkeypatch.setattr(console_resources, "_query_pairs", lambda _: (("normalized", "true"),))
        monkeypatch.setattr(console_resources, "dump_response", dump_response)
        app = Flask(__name__)

        with app.test_request_context("/", method="POST"):
            result = _invoke(class_name, method_name, *route_args)

        assert len(delegate.calls) == 1
        call_fields = delegate.last_call.kwargs
        assert call_fields["tenant_id"] == "tenant-1"
        assert call_fields.get("account_id", call_fields.get("actor_account_id")) == "account-1"
        for field_name, expected in expected_fields.items():
            assert call_fields[field_name] == expected
        if "payload" in call_fields:
            if class_name.__name__ == "KnowledgeFSSpaceSourceApi" and method_name.__name__ == "patch":
                forwarded = narrowed(call_fields["payload"], BaseModel)
                source_update = narrowed(payload, KnowledgeFSSourceUpdatePayload)
                assert forwarded.model_dump(exclude_none=True) == source_update.model_dump(exclude_none=True)
            else:
                assert call_fields["payload"] is payload
        if "members" in call_fields:
            assert call_fields["members"] == ("member-1",)
        if "idempotency_key" in call_fields:
            assert call_fields["idempotency_key"] == "idempotency-1"
        if dump_response.calls:
            assert dump_response.last_call.args[1] is _RAW_RESULT
        else:
            assert result == ("", HTTPStatus.NO_CONTENT)

    @staticmethod
    def test_console_document_reference_delegates_exact_asset_identity(monkeypatch: pytest.MonkeyPatch) -> None:
        facade = FakeComponent(resolve_document_reference=Recorder(_RAW_RESULT))
        runtime = FakeRuntime(facade=facade)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/?document_asset_id=asset-1&document_asset_version=7"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceDocumentReferenceApi,
                console_resources.KnowledgeFSSpaceDocumentReferenceApi.get,
                "space-1",
            )

        assert result is _RAW_RESULT
        assert facade.resolve_document_reference.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="space-1",
                document_asset_id="asset-1",
                document_asset_version=7,
            )
        ]

    @staticmethod
    def test_console_space_list_preserves_repeated_creator_filters(monkeypatch: pytest.MonkeyPatch) -> None:
        application = FakeComponent(list_spaces=Recorder(_RAW_RESULT))
        runtime = FakeRuntime(application=application)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context(
            "/?page=2&limit=10&creator_ids=creator-1&creator_ids=creator-2&tag_ids=tag-1&tag_ids=tag-2&query=%20Support%20"
        ):
            result = _invoke(console_resources.KnowledgeFSSpacesApi, console_resources.KnowledgeFSSpacesApi.get)

        assert application.list_spaces.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                page=2,
                limit=10,
                creator_ids=["creator-1", "creator-2"],
                tag_ids=["tag-1", "tag-2"],
                query="Support",
            )
        ]
        assert result is _RAW_RESULT

    @staticmethod
    def test_console_source_update_does_not_start_sync_before_resource_selection(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        facade = FakeComponent(update_source=Recorder(_RAW_RESULT))
        runtime = FakeRuntime(facade=facade)
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "expectedVersion": 3,
                "status": "disabled",
                "uri": "https://new.example.com",
            }
        )
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/", method="PATCH"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceSourceApi,
                console_resources.KnowledgeFSSpaceSourceApi.patch,
                "space-1",
                "source-1",
            )

        forwarded = narrowed(facade.update_source.last_call.kwargs["payload"], KnowledgeFSAtomicSourceUpdatePayload)
        assert forwarded is not payload
        assert forwarded.status == "disabled"
        assert forwarded.sync_after_update is None
        assert result is _RAW_RESULT

    @staticmethod
    @pytest.mark.parametrize(
        ("selection", "expected_import_kind"),
        [
            (
                {"kind": "website_crawl", "sourceUrls": ["https://new.example.com/a"]},
                "website-crawl-import",
            ),
            (
                {
                    "kind": "online_document",
                    "items": [
                        {
                            "pageId": "page-1",
                            "providerItemId": "provider-page-1",
                            "type": "page",
                            "workspaceId": "workspace-1",
                        }
                    ],
                },
                "online-document-import",
            ),
            (
                {
                    "kind": "online_drive",
                    "items": [{"id": "file-1", "name": "Plan.pdf", "providerItemId": "provider-file-1"}],
                },
                "online-drive-import",
            ),
        ],
    )
    def test_console_source_update_commits_complete_edit_selection(
        monkeypatch: pytest.MonkeyPatch,
        selection: dict[str, object],
        expected_import_kind: str,
    ) -> None:
        selection_kind = selection["kind"]
        assert isinstance(selection_kind, str)
        provider_kind = {"online_document": "online-document", "online_drive": "online-drive"}.get(selection_kind)
        original = source_response(
            metadata={"providerKind": provider_kind} if provider_kind is not None else {},
            type="web" if selection_kind == "website_crawl" else "connector",
            uri="https://old.example.com",
        )
        updated = source_response(sync_workflow=None)
        facade = FakeComponent(
            get_source=Recorder(results=[original, updated]),
            update_source=Recorder(source_response(version=4)),
        )
        workflow = KnowledgeFSSourceWorkflowResponse.model_validate(
            {
                "checkpoint": "queued",
                "created_at": datetime(2026, 1, 1, tzinfo=UTC),
                "execution_attempts": 0,
                "id": "workflow-1",
                "knowledge_space_id": "space-1",
                "kind": "source-import",
                "max_execution_attempts": 3,
                "progress_completed": 0,
                "progress_failed": 0,
                "progress_skipped": 0,
                "state": "queued",
                "updated_at": datetime(2026, 1, 1, tzinfo=UTC),
            }
        )
        runtime = FakeRuntime(facade=facade)
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "expectedVersion": 3,
                "name": "Edited source",
                "selection": selection,
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )
        commit = Recorder(workflow)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(source_edit_service, "commit_source_import", commit)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/", method="PATCH"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceSourceApi,
                console_resources.KnowledgeFSSpaceSourceApi.patch,
                "space-1",
                "source-1",
            )

        assert facade.update_source.calls == []
        source_payload = narrowed(commit.last_call.kwargs["source_update"], KnowledgeFSSourceImportConfigurationPayload)
        assert source_payload.status == "disabled"
        import_payload = narrowed(commit.last_call.kwargs["payload"], BaseModel)
        assert import_payload.model_dump()["kind"] == expected_import_kind
        assert commit.last_call.kwargs["idempotency_key"] == "source-edit:source-1:3"
        assert updated.sync_workflow is workflow
        assert result is updated

    @staticmethod
    def test_console_source_update_does_not_import_an_unchanged_complete_selection(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        source = source_response(
            metadata={"crawled": {"https://example.com/a": {}}},
            sync_policy=None,
            type="web",
            uri="https://example.com",
            version=3,
        )
        facade = FakeComponent(
            get_source=Recorder(source),
            get_source_sync_policy=Recorder(sync_policy_response(revision=2)),
            update_source=Recorder(source),
            update_source_sync_policy=Recorder(),
        )
        runtime = FakeRuntime(facade=facade)
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {"kind": "website_crawl", "sourceUrls": ["https://example.com/a"]},
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )
        commit = Recorder()
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(source_edit_service, "commit_source_import", commit)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/", method="PATCH"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceSourceApi,
                console_resources.KnowledgeFSSpaceSourceApi.patch,
                "space-1",
                "source-1",
            )

        assert len(facade.update_source.calls) == 1
        assert commit.calls == []
        assert facade.update_source_sync_policy.calls == []
        command = narrowed(facade.update_source.last_call.kwargs["payload"], KnowledgeFSAtomicSourceUpdatePayload)
        assert command.expected_version == 3
        assert command.expected_policy_revision == 2
        assert command.sync_policy is not None
        assert command.sync_policy.mode == "interval"
        assert result is source

    @staticmethod
    def test_source_edit_reimports_when_selection_adds_a_canonical_duplicate() -> None:
        source = source_response(
            metadata={"crawled": {"https://docs.dify.ai/a": {}}},
            status="active",
            type="web",
            uri="https://docs.dify.ai",
        )
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {
                    "kind": "website_crawl",
                    "sourceUrls": [
                        "https://docs.dify.ai/a/",
                        "https://DOCS.dify.ai:443/a#section",
                    ],
                },
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )

        assert source_edit_service.source_edit_requires_import(source, payload) is True

    @staticmethod
    def test_source_edit_ignores_order_when_canonical_url_multiplicity_is_unchanged() -> None:
        source = source_response(
            metadata={
                "crawled": {
                    "https://docs.dify.ai/a/": {},
                    "https://DOCS.dify.ai:443/a#stored": {},
                }
            },
            status="active",
            type="web",
            uri="https://docs.dify.ai",
        )
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {
                    "kind": "website_crawl",
                    "sourceUrls": [
                        "https://docs.dify.ai/a#selected",
                        "https://docs.dify.ai/a/",
                    ],
                },
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )

        assert source_edit_service.source_edit_requires_import(source, payload) is False

    @staticmethod
    def test_source_edit_uses_latest_effective_website_selection_instead_of_stale_crawl_metadata() -> None:
        source = source_response(
            metadata={
                "crawled": {"https://docs.dify.ai/old": {}},
                "initialPreview": {"canonicalSourceUrls": ["https://docs.dify.ai/old"]},
                "__knowledgeFsWebsiteSelection": {
                    "sourceUrls": ["https://docs.dify.ai/current/"],
                    "version": 1,
                },
            },
            status="active",
            type="web",
            uri="https://docs.dify.ai",
        )
        unchanged = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {
                    "kind": "website_crawl",
                    "sourceUrls": ["https://DOCS.dify.ai:443/current#selected"],
                },
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )
        changed = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {
                    "kind": "website_crawl",
                    "sourceUrls": ["https://docs.dify.ai/old"],
                },
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )

        assert source_edit_service.source_edit_requires_import(source, unchanged) is False
        assert source_edit_service.source_edit_requires_import(source, changed) is True

    @staticmethod
    def test_source_edit_reimports_an_unchanged_selection_when_source_is_in_error() -> None:
        provider_item_id = '["workspace-a","page-a"]'
        identity_hash = sha256(f"online-document\0{provider_item_id}".encode()).hexdigest()
        source = source_response(
            metadata={
                "providerKind": "online-document",
                "__knowledgeFsProviderSelection": {"identityHashes": [identity_hash]},
            },
            status="error",
            type="connector",
            uri="notion://connection-a",
        )
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {
                "selection": {
                    "kind": "online_document",
                    "items": [
                        {
                            "pageId": "page-a",
                            "providerItemId": provider_item_id,
                            "type": "page",
                            "workspaceId": "workspace-a",
                        }
                    ],
                },
                "syncPolicy": {"enabled": True, "mode": "interval"},
            }
        )

        assert source_edit_service.source_edit_requires_import(source, payload) is True

    @staticmethod
    def test_console_source_update_applies_policy_without_creating_import_work(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        source = source_response(version=5, sync_policy=None)
        policy = sync_policy_response(revision=3)
        source.sync_policy = policy
        facade = FakeComponent(
            get_source=Recorder(source),
            get_source_sync_policy=Recorder(sync_policy_response(revision=2)),
            update_source=Recorder(source),
            update_source_sync_policy=Recorder(),
        )
        runtime = FakeRuntime(facade=facade)
        payload = KnowledgeFSSourceUpdatePayload.model_validate(
            {"syncPolicy": {"customIntervalSeconds": 7200, "enabled": True, "mode": "custom"}}
        )
        commit = Recorder()
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(source_edit_service, "commit_source_import", commit)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/", method="PATCH"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceSourceApi,
                console_resources.KnowledgeFSSpaceSourceApi.patch,
                "space-1",
                "source-1",
            )

        assert len(facade.update_source.calls) == 1
        assert commit.calls == []
        assert facade.update_source_sync_policy.calls == []
        policy_payload = narrowed(
            facade.update_source.last_call.kwargs["payload"], KnowledgeFSAtomicSourceUpdatePayload
        )
        assert policy_payload.expected_policy_revision == 2
        assert policy_payload.expected_version == 5
        assert policy_payload.sync_policy is not None
        assert policy_payload.sync_policy.custom_interval_seconds == 7200
        assert source.sync_policy is policy
        assert result is source

    @staticmethod
    def test_console_metadata_delete_forwards_row_version_cas(monkeypatch: pytest.MonkeyPatch) -> None:
        facade = FakeComponent(delete_metadata_field=Recorder(_RAW_RESULT))
        runtime = FakeRuntime(facade=facade)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "dump_response", lambda _schema, raw: raw)
        app = Flask(__name__)

        with app.test_request_context("/?expectedRowVersion=7", method="DELETE"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceMetadataFieldApi,
                console_resources.KnowledgeFSSpaceMetadataFieldApi.delete,
                "space-1",
                "field-1",
            )

        assert facade.delete_metadata_field.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="space-1",
                field_id="field-1",
                expected_row_version=7,
            )
        ]
        assert result is _RAW_RESULT

    @staticmethod
    def test_console_overview_stats_composes_kfs_metrics_with_dify_app_bindings(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        stats = KnowledgeFSOverviewBaseStatsResponse.model_validate(
            {
                "current": {
                    "freshSourceCount": 2,
                    "knowledgeCount": 13,
                    "latestSourceSyncAt": "2026-07-23T11:00:00.000Z",
                    "linkedAppCount": 0,
                    "sourceCount": 3,
                    "staleSourceCount": 1,
                },
                "generatedAt": "2026-07-23T11:59:59.000Z",
                "knowledgeSpaceId": "knowledge-space-1",
                "windows": {
                    "24h": {
                        "answerRate": 0.8,
                        "answeredQueryCount": 8,
                        "queryCount": 10,
                        "since": "2026-07-22T12:00:00.000Z",
                    },
                    "7d": {
                        "answerRate": 0.75,
                        "answeredQueryCount": 75,
                        "queryCount": 100,
                        "since": "2026-07-16T12:00:00.000Z",
                    },
                    "30d": {
                        "answerRate": 0.7,
                        "answeredQueryCount": 210,
                        "queryCount": 300,
                        "since": "2026-06-23T12:00:00.000Z",
                    },
                },
            }
        )
        outcomes = KnowledgeFSOverviewQueryOutcomesResponse.model_validate(
            {
                "buckets": [],
                "current": {
                    "answerRate": 0.8,
                    "answered": 96,
                    "lowConfidence": 12,
                    "noEvidence": 12,
                    "queryCount": 120,
                },
                "generatedAt": "2026-07-23T12:00:00.000Z",
                "knowledgeSpaceId": "knowledge-space-1",
                "previous": {
                    "answerRate": 0.85,
                    "answered": 85,
                    "lowConfidence": 8,
                    "noEvidence": 7,
                    "queryCount": 100,
                },
                "previousSince": "2026-07-09T12:00:00.000Z",
                "since": "2026-07-16T12:00:00.000Z",
                "window": "7d",
            }
        )
        runtime = FakeRuntime(
            facade=FakeComponent(
                get_overview_query_outcomes=Recorder(outcomes),
                get_overview_stats=Recorder(stats),
            ),
            app_bindings=FakeComponent(count_active=Recorder(7)),
        )
        dump_response = Recorder(effect=lambda _schema, raw: raw)
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(console_resources, "_console_services", lambda: runtime)
        monkeypatch.setattr(console_resources, "dump_response", dump_response)
        app = Flask(__name__)

        with app.test_request_context("/?window=7d"):
            result = _invoke(
                console_resources.KnowledgeFSSpaceOverviewStatsApi,
                console_resources.KnowledgeFSSpaceOverviewStatsApi.get,
                "control-space-1",
            )

        assert runtime.facade.get_overview_stats.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="control-space-1",
            )
        ]
        assert runtime.facade.get_overview_query_outcomes.calls == [
            invocation(
                tenant_id="tenant-1",
                account_id="account-1",
                control_space_id="control-space-1",
                window="7d",
            )
        ]
        assert runtime.app_bindings.count_active.calls == [
            invocation(
                tenant_id="tenant-1",
                actor_account_id="account-1",
                control_space_id="control-space-1",
            )
        ]
        result = narrowed(result, KnowledgeFSOverviewStatsResponse)
        assert result.documents == 13
        assert result.linked_apps == 7
        assert result.queries.value == 120
        assert result.queries.previous_value == 100
        assert result.queries.change_rate == pytest.approx(0.2)
        assert result.answer_rate.value == pytest.approx(0.8)
        assert result.answer_rate.change_percentage_points == pytest.approx(-5)
        assert result.freshness_seconds == 3600
        assert result.generated_at == outcomes.generated_at
        assert dump_response.last_call.args[1] is result

    @staticmethod
    @pytest.mark.parametrize(
        ("class_name", "method_name", "route_args", "operation_id", "expected_fields"),
        _SERVICE_DELEGATION_CASES,
    )
    def test_service_resources_bind_route_identifiers_to_one_declared_operation(
        monkeypatch: pytest.MonkeyPatch,
        class_name: type[Resource],
        method_name: Callable[..., object],
        route_args: tuple[object, ...],
        operation_id: str,
        expected_fields: dict[str, object],
    ) -> None:
        payload = object()
        execute = Recorder(_RAW_RESULT)
        dump_response = Recorder(effect=lambda schema, raw: (schema.__name__, raw))
        monkeypatch.setattr(service_resources, "_execute_service_operation", execute)
        monkeypatch.setattr(service_resources, "_payload", lambda _: payload)
        monkeypatch.setattr(service_resources, "_idempotency_key", lambda: "idempotency-1")
        monkeypatch.setattr(service_resources, "_query_pairs", lambda _: (("normalized", "true"),))
        monkeypatch.setattr(service_resources, "dump_response", dump_response)
        monkeypatch.setattr(service_resources, "durable_page_import", lambda value: value)
        monkeypatch.setattr(service_resources, "durable_file_import", lambda value: value)
        monkeypatch.setattr(
            service_resources,
            "_deletion_accepted",
            lambda _space, raw: dump_response(service_resources.KnowledgeFSDurableDeletionAcceptedResponse, raw),
        )
        monkeypatch.setattr(
            service_resources,
            "_bulk_deletion_accepted",
            lambda _space, raw: dump_response(service_resources.KnowledgeFSDurableDeletionAcceptedResponse, raw),
        )
        app = Flask(__name__)

        with app.test_request_context("/", method="POST", headers={"Idempotency-Key": "idempotency-1"}):
            _invoke(class_name, method_name, *route_args)

        assert len(execute.calls) == 1
        call_fields = execute.last_call.kwargs
        assert call_fields["control_space_id"] == "space-1"
        assert call_fields["operation_id"] == operation_id
        for field_name, expected in expected_fields.items():
            assert call_fields[field_name] == expected
        if "payload" in call_fields:
            assert call_fields["payload"] is payload
        if "headers" in call_fields:
            assert call_fields["headers"] == (("Idempotency-Key", "idempotency-1"),)
        if "query" in call_fields:
            assert call_fields["query"] == (("normalized", "true"),)
        assert dump_response.last_call.args[1] is _RAW_RESULT

    @staticmethod
    @pytest.mark.parametrize(
        ("class_name", "method_name", "operation_id"),
        [
            (
                service_resources.KnowledgeFSServiceDocumentsApi,
                service_resources.KnowledgeFSServiceDocumentsApi.get,
                "listDocuments",
            ),
            (
                service_resources.KnowledgeFSServiceSettingsApi,
                service_resources.KnowledgeFSServiceSettingsApi.get,
                "getSettings",
            ),
            (
                service_resources.KnowledgeFSServiceSettingsApi,
                service_resources.KnowledgeFSServiceSettingsApi.patch,
                "updateSettings",
            ),
            (
                service_resources.KnowledgeFSServiceSourcesApi,
                service_resources.KnowledgeFSServiceSourcesApi.get,
                "listSources",
            ),
            (
                service_resources.KnowledgeFSServiceSourcesApi,
                service_resources.KnowledgeFSServiceSourcesApi.post,
                "createSource",
            ),
            (
                service_resources.KnowledgeFSServiceResearchTasksApi,
                service_resources.KnowledgeFSServiceResearchTasksApi.get,
                "listResearchTasks",
            ),
            (
                service_resources.KnowledgeFSServiceTracesApi,
                service_resources.KnowledgeFSServiceTracesApi.get,
                "listTraces",
            ),
        ],
    )
    @pytest.mark.parametrize("cursor", [None, "cursor-2"])
    def test_service_credential_routes_validate_profile_before_facade_delegation(
        monkeypatch: pytest.MonkeyPatch,
        class_name: type[Resource],
        method_name: Callable[..., object],
        operation_id: str,
        cursor: str | None,
    ) -> None:
        facade = FakeComponent(
            execute_service=Recorder(_RAW_RESULT),
            update_service_settings=Recorder(_SettingsUpdateResult()),
        )
        runtime = FakeRuntime(facade=facade)
        profile = object()
        validate_profile = Recorder(profile)
        monkeypatch.setattr(service_resources, "_runtime", lambda: runtime)
        monkeypatch.setattr(service_resources, "_profile", validate_profile)
        monkeypatch.setattr(service_resources, "_payload", lambda _: object())
        monkeypatch.setattr(service_resources, "dump_response", lambda schema, raw: (schema.__name__, raw))
        app = Flask(__name__)
        query_string = {"cursor": cursor} if cursor is not None else None

        with app.test_request_context("/", method="POST", query_string=query_string):
            _invoke(class_name, method_name, "space-1")

        assert validate_profile.calls == [invocation(runtime, operation_id=operation_id, control_space_id="space-1")]
        if operation_id == "updateSettings":
            assert facade.update_service_settings.last_call.kwargs["profile"] is profile
            assert facade.execute_service.calls == []
            return
        assert facade.execute_service.last_call.kwargs["profile"] is profile
        assert facade.execute_service.last_call.kwargs["operation_id"] == operation_id
        if "query" in facade.execute_service.last_call.kwargs:
            expected_query = (("limit", "50"),) + ((("cursor", cursor),) if cursor else ())
            assert facade.execute_service.last_call.kwargs["query"] == expected_query

    @staticmethod
    @pytest.mark.parametrize(
        "class_name",
        [
            console_resources.KnowledgeFSSpaceQueriesApi,
        ],
    )
    def test_deprecated_buffered_routes_fail_closed(
        class_name: type[console_resources.KnowledgeFSSpaceQueriesApi],
    ) -> None:
        with pytest.raises(KnowledgeFSOperationUnavailableError, match="deprecated"):
            _invoke(class_name, class_name.post, "space-1")

    @staticmethod
    def test_console_stream_capabilities_bind_the_authorized_resource(monkeypatch: pytest.MonkeyPatch) -> None:
        broker = FakeComponent(issue_interactive=Recorder(issued_capability()))
        payloads = iter(
            [
                KnowledgeFSQueryCreatePayload(query="question", mode="deep"),
                KnowledgeFSStreamCapabilityPayload(control_space_id="space-2"),
            ]
        )
        apply_config_overrides(monkeypatch, CONSOLE_API_URL="https://dify.example")
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(
            console_resources,
            "_console_services",
            lambda: FakeRuntime(broker=broker),
        )
        monkeypatch.setattr(console_resources, "_payload", lambda _: next(payloads))
        monkeypatch.setattr(console_resources, "dump_response", lambda _, response: response)
        app = Flask(__name__)

        with app.test_request_context("/", method="POST"):
            query = _invoke(
                console_resources.KnowledgeFSSpaceQueryAdmissionApi,
                console_resources.KnowledgeFSSpaceQueryAdmissionApi.post,
                "space-1",
            )
            task = _invoke(
                console_resources.KnowledgeFSTaskStreamCapabilityApi,
                console_resources.KnowledgeFSTaskStreamCapabilityApi.post,
                "task/1",
            )
            legacy_query = _invoke(
                console_resources.KnowledgeFSSpaceQueryStreamCapabilityApi,
                console_resources.KnowledgeFSSpaceQueryStreamCapabilityApi.post,
                "space-1",
            )

        query = narrowed(query, KnowledgeFSQueryAdmissionResponse)
        task = narrowed(task, KnowledgeFSStreamCapabilityResponse)
        legacy_query = narrowed(legacy_query, KnowledgeFSQueryStreamCapabilityResponse)
        assert query.request.knowledge_space_id == "knowledge-space-1"
        assert query.url == "https://dify.example/console/api/knowledge-fs/query-stream"
        assert (
            task.url == "https://dify.example/console/api/knowledge-fs/research-tasks/task%2F1/events"
            "?knowledgeSpaceId=knowledge-space-1"
        )
        assert legacy_query.url == "https://dify.example/console/api/knowledge-fs/query-stream"
        assert broker.issue_interactive.calls[0].kwargs["operation_id"] == "createQuery"
        assert broker.issue_interactive.calls[1].kwargs == {
            "tenant_id": "tenant-1",
            "account_id": "account-1",
            "control_space_id": "space-2",
            "operation_id": "streamResearchTask",
            "resource_id": "task/1",
        }
        assert broker.issue_interactive.calls[2].kwargs["operation_id"] == "createQuery"

    @staticmethod
    def test_service_query_admission_binds_profile_space_and_payload(monkeypatch: pytest.MonkeyPatch) -> None:
        broker = FakeComponent(issue_service=Recorder(issued_capability()))
        runtime = FakeRuntime(broker=broker)
        profile = object()
        apply_config_overrides(monkeypatch, SERVICE_API_URL="https://api.dify.example")
        monkeypatch.setattr(service_resources, "_runtime", lambda: runtime)
        monkeypatch.setattr(service_resources, "_profile", lambda *_args, **_kwargs: profile)
        monkeypatch.setattr(service_resources, "_payload", lambda _: KnowledgeFSQueryCreatePayload(query="question"))
        monkeypatch.setattr(service_resources, "dump_response", lambda _, response: response)
        app = Flask(__name__)

        with app.test_request_context("/", method="POST"):
            response = _invoke(
                service_resources.KnowledgeFSServiceQueryAdmissionApi,
                service_resources.KnowledgeFSServiceQueryAdmissionApi.post,
                "space-1",
            )

        assert broker.issue_service.calls == [invocation(profile=profile, operation_id="createQuery")]
        response = narrowed(response, KnowledgeFSQueryAdmissionResponse)
        assert response.request.knowledge_space_id == "knowledge-space-1"
        assert response.request.query == "question"
        assert response.url == "https://api.dify.example/v1/knowledge-fs/query-stream"

    @staticmethod
    def test_console_resource_helpers_validate_feature_payload_headers_and_query_pairs(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        runtime = FakeRuntime()
        session_maker = object()
        get_runtime = Recorder(runtime)
        apply_config_overrides(monkeypatch, DEPLOYMENT_EDITION=DeploymentEdition.CLOUD, KNOWLEDGE_FS_ENABLED=True)
        monkeypatch.setattr(console_resources.session_factory, "get_session_maker", lambda: session_maker)
        monkeypatch.setattr(console_resources, "get_knowledge_fs_runtime", get_runtime)
        monkeypatch.setattr(
            console_resources,
            "current_account_with_tenant",
            lambda: (_knowledge_fs_resource_delegation_account("account-1"), "tenant-1"),
        )
        app = Flask(__name__)

        assert console_resources._console_services() is runtime
        assert get_runtime.calls == [invocation(session_maker)]
        assert console_resources._actor() == ("account-1", "tenant-1")
        query = KnowledgeFSQueryCreatePayload(query="question", mode="fast", active_document_ids=["doc-1"])
        assert console_resources._query_pairs(query) == (
            ("query", "question"),
            ("mode", "fast"),
            ("activeDocumentIds", "['doc-1']"),
            ("activeEntityIds", "[]"),
        )
        with app.test_request_context(
            "/",
            method="POST",
            json={"query": "question"},
            headers={"Idempotency-Key": "request-key"},
        ):
            assert console_resources._payload(KnowledgeFSQueryCreatePayload).query == "question"
            assert console_resources._idempotency_key() == "request-key"

        apply_config_overrides(monkeypatch, DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
        with pytest.raises(NotFound):
            console_resources._console_services()

        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_COMMUNITY_DEV_ENABLED=True)
        assert console_resources._console_services() is runtime

        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_ENABLED=False)
        with pytest.raises(NotFound):
            console_resources._console_services()

    @staticmethod
    def test_service_resource_helpers_validate_feature_bearer_headers_and_boolean_queries(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        runtime = FakeRuntime()
        session_maker = object()
        get_runtime = Recorder(runtime)
        apply_config_overrides(monkeypatch, DEPLOYMENT_EDITION=DeploymentEdition.CLOUD, KNOWLEDGE_FS_ENABLED=True)
        monkeypatch.setattr(service_resources.session_factory, "get_session_maker", lambda: session_maker)
        monkeypatch.setattr(service_resources, "get_knowledge_fs_runtime", get_runtime)
        app = Flask(__name__)

        assert service_resources._runtime() is runtime
        assert get_runtime.calls == [invocation(session_maker)]

        class Query(BaseModel):
            enabled: bool = True
            disabled: bool = False
            count: int = 2

        query = Query()
        assert service_resources._query_pairs(query) == (
            ("enabled", "true"),
            ("disabled", "false"),
            ("count", "2"),
        )
        with app.test_request_context(
            "/",
            method="POST",
            json={"query": "question"},
            headers={"Authorization": "bEaReR  credential-value  ", "Idempotency-Key": "request-key"},
        ):
            assert service_resources._payload(KnowledgeFSQueryCreatePayload).query == "question"
            assert service_resources._idempotency_key() == "request-key"

        apply_config_overrides(monkeypatch, DEPLOYMENT_EDITION=DeploymentEdition.COMMUNITY)
        with pytest.raises(NotFound):
            service_resources._runtime()

        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_COMMUNITY_DEV_ENABLED=True)
        assert service_resources._runtime() is runtime

        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_ENABLED=False)
        with pytest.raises(NotFound):
            service_resources._runtime()

    @staticmethod
    def test_console_request_rejections_preserve_http_status_contracts() -> None:
        from services.knowledge_fs.product_remote import KnowledgeFSProductRequestRejectedError

        expected: dict[Literal[400, 403, 409, 413, 422, 429, 503, 504], type[BaseHTTPException]] = {
            400: KnowledgeFSInvalidRequestHTTPError,
            403: KnowledgeFSAccessDeniedHTTPError,
            409: KnowledgeFSConflictHTTPError,
            413: KnowledgeFSRequestTooLargeHTTPError,
            422: KnowledgeFSRequestRejectedHTTPError,
            429: KnowledgeFSRateLimitHTTPError,
            503: KnowledgeFSOperationUnavailableHTTPError,
            504: KnowledgeFSTimeoutHTTPError,
        }
        for status, http_error in expected.items():
            guarded = console_resources._knowledge_fs_errors(
                raising(KnowledgeFSProductRequestRejectedError(status_code=status))
            )

            with pytest.raises(http_error) as raised:
                guarded()

            assert raised.value.code == status
            assert raised.value.data == {
                "code": http_error.error_code,
                "message": http_error.description,
                "status": status,
            }

    @staticmethod
    @pytest.mark.parametrize(
        ("status", "failure_code", "category", "safe_message"),
        [
            (
                503,
                "DOCUMENT_COUNT_QUOTA_UNAVAILABLE",
                "dependency",
                "The workspace document quota could not be verified. Try again later.",
            ),
            (
                503,
                "VECTOR_SPACE_QUOTA_UNAVAILABLE",
                "dependency",
                "The workspace vector storage quota could not be verified. Try again later.",
            ),
            (504, "KNOWLEDGE_FS_TIMEOUT", "timeout", "The Agent Knowledge Base operation timed out. Try again later."),
        ],
    )
    def test_console_unavailable_and_timeout_rejections_preserve_safe_failure_metadata(
        status: Literal[503, 504], failure_code: str, category: str, safe_message: str
    ) -> None:
        from services.knowledge_fs.product_remote import KnowledgeFSProductRequestRejectedError

        expected_failure = {
            "action": "retry",
            "category": category,
            "code": failure_code,
            "message": safe_message,
            "retryPolicy": "manual",
            "traceId": "trace-quota",
            "parameters": {"retryAfterSeconds": 30},
        }
        failure = KnowledgeFSPublicFailureResponse.model_validate(
            {**expected_failure, "message": "Private upstream diagnostic that must not reach the client"}
        )
        guarded = console_resources._knowledge_fs_errors(
            raising(KnowledgeFSProductRequestRejectedError(status_code=status, failure=failure))
        )
        http_error = KnowledgeFSOperationUnavailableHTTPError if status == 503 else KnowledgeFSTimeoutHTTPError

        with pytest.raises(http_error) as raised:
            guarded()

        assert raised.value.code == status
        assert raised.value.data == {
            "code": http_error.error_code,
            "message": safe_message,
            "status": status,
            "failure": expected_failure,
            "details": expected_failure,
        }

    @staticmethod
    def test_console_settings_conflict_exposes_documented_failure_details() -> None:
        from services.knowledge_fs.product_remote import KnowledgeFSProductRequestRejectedError

        failure = KnowledgeFSPublicFailureResponse.model_validate(
            {
                "category": "conflict",
                "code": "KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS",
                "message": "Private worker diagnostic",
                "retryPolicy": "manual",
            }
        )
        guarded = console_resources._knowledge_fs_errors(
            raising(KnowledgeFSProductRequestRejectedError(status_code=409, failure=failure))
        )

        with pytest.raises(KnowledgeFSConflictHTTPError) as raised:
            guarded()

        assert raised.value.data is not None
        assert raised.value.data["details"] == failure.model_dump(by_alias=True, exclude_none=True)
        assert raised.value.data["failure"] == raised.value.data["details"]
        assert "Private worker diagnostic" not in str(raised.value.data)

    @staticmethod
    def test_console_request_rejection_preserves_safe_failure_metadata() -> None:
        from services.knowledge_fs.product_remote import KnowledgeFSProductRequestRejectedError

        failure = KnowledgeFSPublicFailureResponse.model_validate(
            {
                "action": "configure_model",
                "category": "configuration",
                "code": "MODEL_SELECTION_NOT_FOUND",
                "message": "Select another model before retrying.",
                "retryPolicy": "after_configuration",
                "traceId": "trace-model",
            }
        )
        guarded = console_resources._knowledge_fs_errors(
            raising(KnowledgeFSProductRequestRejectedError(status_code=422, failure=failure))
        )

        with pytest.raises(KnowledgeFSRequestRejectedHTTPError) as raised:
            guarded()

        assert raised.value.data == {
            "code": "knowledge_fs_request_rejected",
            "message": "The Agent Knowledge Base operation requires a configuration change before it can continue.",
            "status": 422,
            "details": failure.model_dump(by_alias=True, exclude_none=True),
            "failure": {
                "action": "configure_model",
                "category": "configuration",
                "code": "MODEL_SELECTION_NOT_FOUND",
                "message": "The Agent Knowledge Base operation requires a configuration change before it can continue.",
                "retryPolicy": "after_configuration",
                "traceId": "trace-model",
            },
        }

    @staticmethod
    def test_jwks_resource_fails_closed_for_disabled_missing_and_misconfigured_issuers(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        from services.knowledge_fs_capability import KnowledgeFSCapabilityConfigurationError

        app = Flask(__name__)
        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=False)
        with app.app_context(), pytest.raises(NotFound):
            console_resources.KnowledgeFSJWKSApi().get()

        apply_config_overrides(monkeypatch, KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=True)
        monkeypatch.setattr(console_resources.session_factory, "get_session_maker", lambda: object())
        monkeypatch.setattr(console_resources, "create_configured_knowledge_fs_capability_issuer", lambda **_: None)
        with app.app_context(), pytest.raises(NotFound):
            console_resources.KnowledgeFSJWKSApi().get()

        def misconfigured(**_: object) -> None:
            raise KnowledgeFSCapabilityConfigurationError("missing signing key")

        monkeypatch.setattr(console_resources, "create_configured_knowledge_fs_capability_issuer", misconfigured)
        with app.app_context(), pytest.raises(ServiceUnavailable, match="not configured"):
            console_resources.KnowledgeFSJWKSApi().get()

    @staticmethod
    def test_console_error_adapter_maps_every_domain_boundary_to_the_stable_http_contract() -> None:
        from pydantic import ValidationError

        from services.knowledge_fs.app_binding_management import KnowledgeFSAppBindingManagementError
        from services.knowledge_fs.control_plane_service import KnowledgeFSControlPlaneInvariantError
        from services.knowledge_fs.product_authorization import KnowledgeFSProductNotFoundError
        from services.knowledge_fs.product_remote import (
            KnowledgeFSProductRemoteError,
            KnowledgeFSProductResourceNotFoundError,
        )
        from services.knowledge_fs_capability import KnowledgeFSCapabilityConfigurationError

        with pytest.raises(ValidationError) as raised_validation:
            KnowledgeFSQueryCreatePayload.model_validate({"query": ""})
        validation_error = raised_validation.value
        mappings = (
            (KnowledgeFSProductNotFoundError("hidden"), KnowledgeFSSpaceNotFoundHTTPError),
            (KnowledgeFSProductResourceNotFoundError("missing child"), KnowledgeFSResourceNotFoundHTTPError),
            (KnowledgeFSOperationUnavailableError("manifest mismatch"), KnowledgeFSOperationUnavailableHTTPError),
            (KnowledgeFSProductRemoteError("upstream unavailable"), KnowledgeFSUpstreamUnavailableHTTPError),
            (KnowledgeFSAppBindingManagementError("invalid binding"), KnowledgeFSInvalidRequestHTTPError),
            (KnowledgeFSControlPlaneInvariantError("missing revision"), KnowledgeFSInvalidRequestHTTPError),
            (validation_error, KnowledgeFSInvalidRequestHTTPError),
            (PermissionError("forbidden"), KnowledgeFSAccessDeniedHTTPError),
            (KnowledgeFSCapabilityConfigurationError("missing issuer"), KnowledgeFSOperationUnavailableHTTPError),
        )

        for domain_error, http_error in mappings:
            guarded = console_resources._knowledge_fs_errors(raising(domain_error))

            with pytest.raises(http_error):
                guarded()

        assert KnowledgeFSUpstreamUnavailableHTTPError.code == HTTPStatus.SERVICE_UNAVAILABLE

    @staticmethod
    def test_service_error_adapter_maps_every_domain_boundary_to_the_stable_http_contract() -> None:
        from pydantic import ValidationError

        from services.knowledge_fs.product_remote import (
            KnowledgeFSProductRemoteError,
            KnowledgeFSProductRequestRejectedError,
            KnowledgeFSProductResourceNotFoundError,
        )
        from services.knowledge_fs.service_api_authorization import KnowledgeFSServiceApiAuthorizationError

        with pytest.raises(ValidationError) as raised_validation:
            KnowledgeFSQueryCreatePayload.model_validate({"query": ""})
        validation_error = raised_validation.value
        mappings = (
            (KnowledgeFSServiceApiAuthorizationError("revoked"), KnowledgeFSInvalidCredentialHTTPError),
            (
                KnowledgeFSOperationUnavailableError("manifest mismatch"),
                KnowledgeFSServiceOperationUnavailableHTTPError,
            ),
            (
                KnowledgeFSProductResourceNotFoundError("missing child"),
                KnowledgeFSServiceResourceNotFoundHTTPError,
            ),
            (KnowledgeFSProductRemoteError("upstream unavailable"), KnowledgeFSServiceUpstreamUnavailableHTTPError),
            (validation_error, KnowledgeFSServiceInvalidRequestHTTPError),
        )

        for domain_error, http_error in mappings:
            guarded = service_resources._service_api_errors(raising(domain_error))

            with pytest.raises(http_error):
                guarded()

        rejected_mappings = (
            (400, KnowledgeFSServiceInvalidRequestHTTPError),
            (403, KnowledgeFSServiceAccessDeniedHTTPError),
            (409, KnowledgeFSServiceConflictHTTPError),
            (413, KnowledgeFSServiceRequestTooLargeHTTPError),
            (422, KnowledgeFSServiceRequestRejectedHTTPError),
            (429, KnowledgeFSServiceRateLimitHTTPError),
        )
        for status, http_error in rejected_mappings:
            guarded = service_resources._service_api_errors(
                raising(KnowledgeFSProductRequestRejectedError(status_code=status))
            )
            with pytest.raises(http_error):
                guarded()

    @staticmethod
    def test_console_small_file_reader_rejects_malformed_and_empty_multipart_bodies() -> None:
        from io import BytesIO

        from services.knowledge_fs.product_remote import KnowledgeFSProductRequestRejectedError

        app = Flask(__name__)
        with app.test_request_context(
            "/",
            method="POST",
            data=b"x",
            environ_overrides={"CONTENT_LENGTH": str(64 * 1024 + 2)},
        ):
            with pytest.raises(KnowledgeFSProductRequestRejectedError) as too_large:
                console_resources._read_small_file_body(1)
        assert too_large.value.status_code == HTTPStatus.REQUEST_ENTITY_TOO_LARGE

        malformed_payloads = (
            dict[str, object](),
            {"file": (BytesIO(b"content"), "")},
            {"file": (BytesIO(b""), "empty.txt")},
        )
        for payload in malformed_payloads:
            with app.test_request_context("/", method="POST", data=payload, content_type="multipart/form-data"):
                with pytest.raises(KnowledgeFSProductRequestRejectedError) as rejected:
                    console_resources._read_small_file_body(10)
            assert rejected.value.status_code == HTTPStatus.UNPROCESSABLE_ENTITY

    @staticmethod
    def test_console_app_binding_route_rejects_unknown_caller_kind_before_revoke(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        from services.knowledge_fs.app_binding_management import KnowledgeFSAppBindingManagementError

        revoke = Recorder()
        monkeypatch.setattr(console_resources, "_actor", lambda: ("account-1", "tenant-1"))
        monkeypatch.setattr(
            console_resources,
            "_console_services",
            lambda: FakeRuntime(app_bindings=FakeComponent(revoke=revoke)),
        )

        with pytest.raises(KnowledgeFSAppBindingManagementError, match="caller kind"):
            _invoke(
                console_resources.KnowledgeFSSpaceAppBindingApi,
                console_resources.KnowledgeFSSpaceAppBindingApi.delete,
                "space-1",
                "unknown-caller",
                "app-1",
            )

        assert revoke.calls == []

    @staticmethod
    def test_service_profile_hides_unknown_operations_before_dataset_key_authorization(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        authorization = FakeComponent(authorize=Recorder())
        # The profile check must fail before it touches any runtime component but authorization.
        runtime = cast(KnowledgeFSRuntime, FakeRuntime(service_api_authorization=authorization))
        monkeypatch.setattr(service_resources, "product_operation_action", raising(KeyError("unknown")))

        with pytest.raises(KnowledgeFSOperationUnavailableError, match="unknownOperation"):
            service_resources._profile(
                runtime,
                operation_id="unknownOperation",
                control_space_id="space-1",
            )

        assert authorization.authorize.calls == []

    @staticmethod
    def test_service_operation_helper_forwards_the_complete_validated_request(
        monkeypatch: pytest.MonkeyPatch,
    ) -> None:
        profile = object()
        payload = KnowledgeFSQueryCreatePayload(query="question")
        facade = FakeComponent(execute_service=Recorder({"id": "result-1"}))
        runtime = FakeRuntime(facade=facade)
        monkeypatch.setattr(service_resources, "_runtime", lambda: runtime)
        monkeypatch.setattr(service_resources, "_profile", Recorder(profile))

        result = service_resources._execute_service_operation(
            control_space_id="space-1",
            operation_id="createResearchTask",
            payload=payload,
            query=(("cursor", "next"),),
            bind_space_in_body=True,
            resource_id="task-1",
            path_parameters=(("taskId", "task-1"),),
            headers=(("Idempotency-Key", "request-key"),),
        )

        assert result == {"id": "result-1"}
        assert facade.execute_service.calls == [
            invocation(
                profile=profile,
                operation_id="createResearchTask",
                payload=payload,
                query=(("cursor", "next"),),
                bind_space_in_body=True,
                resource_id="task-1",
                path_parameters=(("taskId", "task-1"),),
                headers=(("Idempotency-Key", "request-key"),),
            )
        ]