Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

60.0 KB
Raw Blame
"""Ported from ``tests/notes/test_notes_api.py`` on main (deleted by the
FastAPI migration).

Old surface: ``web/routes/notes_routes.py`` handlers, driven through a bare
Flask app + ``test_request_context``.
New surface: ``web/routers/notes.py`` handlers, driven directly with a dummy
``Request`` (query string in the scope) and explicit ``username`` / ``body``
arguments -- the same "call the real handler over a real in-memory DB" shape,
with the Flask plumbing removed.

Successor audit
---------------
A per-test audit against the branch found 24 of the original 67 fully
superseded (mostly by ``tests/notes/test_notes_router_fastapi.py``,
``tests/security/test_library_notes_authz_fastapi.py`` and
``tests/web/test_pagination_clamping_census.py``). Those are NOT re-ported.
What is ported here is the residue: the assertions no branch test would go
red for. Each class docstring names the gap.

Deliberately dropped, with reasons
----------------------------------
* ``TestNotesAPIDatabase`` / ``TestNotesAPILinkResolution`` /
  ``TestNotesAPISemanticDiff`` -- the version-numbering, backlink,
  synthesis-record, restore and semantic-diff halves are covered by
  ``tests/notes/test_note_models.py``, ``tests/notes/test_note_integration.py``
  and ``tests/security/test_library_notes_authz_fastapi.py``. The two
  genuinely-unpinned ones (``search_notes_for_linking`` filtering and
  ``exclude_note_id``) ARE ported below, because their only branch
  "successors" (``test_note_integration.py::test_search_for_linking_autocomplete``
  and ``::test_exclude_current_note_from_search``) re-implement the ILIKE
  inside the test body and so pin nothing about the service or the route.
* ``TestNonObjectJsonBodyGuard`` -- superseded by
  ``test_notes_router_fastapi.py::test_create_non_object_body_400`` /
  ``::test_update_non_object_body_400`` plus
  ``tests/web/routers/test_notes_body_gate_ordering.py``, which additionally
  proves the gate is declared on every mutating notes route. The Flask
  "guard fires before auth" half is deliberately INVERTED on this branch
  (auth first), so porting it as written would assert the opposite of the
  branch's intent.
* ``TestNotesBodySizeCap`` -- ``arm_notes_body_cap`` and the
  ``CSRFProtect(app)`` registration order do not exist on FastAPI. The
  equivalents are pinned by
  ``tests/web/routers/test_merge_review_fixes.py::test_notes_chunked_oversized_body_is_413``,
  ``tests/web/test_remember_me_and_json_body_cap.py`` and
  ``tests/web/routers/test_notes_body_gate_ordering.py``. Only the constant's
  derivation (``_MAX_JSON_BODY_BYTES == 2 * NOTE_CONTENT_MAX_BYTES``) had no
  successor, and it is ported below as a one-line structural check.
* ``test_update_note_400_on_non_bool_pinned`` -- superseded by
  ``test_notes_router_fastapi.py::test_update_non_bool_pinned_400``.
"""

import asyncio
import inspect
import json as _json
import uuid
from contextlib import contextmanager
from unittest.mock import AsyncMock, MagicMock

import pytest
from fastapi.responses import JSONResponse
from starlette.requests import Request

from local_deep_research.database.models import (
    Collection,
    Document,
    DocumentCollection,
)

from tests.notes.helpers import _generate_hash

USERNAME = "test_user"


# ---------------------------------------------------------------------------
# Harness
# ---------------------------------------------------------------------------


def _route_ctx(monkeypatch, db_session):
    """Point every ``get_user_db_session`` the notes surface uses at the
    in-memory test session, and return the router module.

    Successor of main's ``_route_app``: same two monkeypatches, minus the
    Flask app (FastAPI handlers are plain callables once unwrapped).
    """
    from local_deep_research.web.routers import notes as notes_routes

    @contextmanager
    def fake_session(username=None, password=None):
        yield db_session

    monkeypatch.setattr(
        "local_deep_research.database.session_context.get_user_db_session",
        fake_session,
    )
    monkeypatch.setattr(
        "local_deep_research.research_library.notes.services.note_service.get_user_db_session",
        fake_session,
    )
    return notes_routes


def _unwrap(route_fn):
    """Peel the slowapi rate-limit wrappers (main peeled ``@login_required``)."""
    while hasattr(route_fn, "__wrapped__"):
        route_fn = route_fn.__wrapped__
    return route_fn


def _request(path="/", method="GET", query=""):
    return Request(
        {
            "type": "http",
            "method": method,
            "path": path,
            "query_string": query.encode(),
            "headers": [],
            "session": {"session_id": "sess-1"},
        }
    )


def _call(path, handler, *args, method="GET", json=None):
    """Drive a handler and return ``(payload, status)``.

    ``path`` may carry a ``?query=string``; it is split into the ASGI scope
    so ``request.query_params`` works exactly as Flask's ``request.args``
    did. A ``body`` argument is supplied only to handlers that declare one.
    """
    raw_path, _, query = path.partition("?")
    fn = _unwrap(handler)
    kwargs = {"username": USERNAME}
    if "body" in inspect.signature(fn).parameters:
        kwargs["body"] = json if json is not None else {}
    if inspect.iscoroutinefunction(fn):
        response = asyncio.run(
            fn(_request(raw_path, method, query), *args, **kwargs)
        )
    else:
        response = fn(_request(raw_path, method, query), *args, **kwargs)
    if isinstance(response, JSONResponse):
        return _json.loads(response.body), response.status_code
    return response, 200


def _seed_note(db_session, note_source_type, title="Note"):
    note = Document(
        id=str(uuid.uuid4()),
        title=title,
        text_content="content",
        file_type="note",
        file_size=7,
        document_hash=_generate_hash(str(uuid.uuid4())),
        source_type_id=note_source_type.id,
        tags=[],
    )
    db_session.add(note)
    db_session.commit()
    return note


# ---------------------------------------------------------------------------


class TestNotesAPILinkResolution:
    """``search_notes_for_linking`` -- the wiki-link autocomplete.

    The branch's ``test_note_integration.py`` tests of the same name are
    shadow tests: they run their own ``ilike`` query inside the test body and
    assert on THAT, so deleting the service method's filter (or the route's
    blank-query short circuit) leaves them green. These drive the route.
    """

    def _seed(self, db_session, note_source_type):
        a = _seed_note(db_session, note_source_type, title="Python Basics")
        b = _seed_note(db_session, note_source_type, title="Rust Basics")
        c = _seed_note(db_session, note_source_type, title="Python Advanced")
        return a, b, c

    def test_search_for_linking_query(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        self._seed(db_session, note_source_type)

        payload, status = _call(
            "/notes/api/notes/search-for-linking?query=Python",
            notes_routes.search_notes_for_linking,
        )

        assert status == 200
        titles = {n["title"] for n in payload["notes"]}
        assert titles == {"Python Basics", "Python Advanced"}, payload

    def test_search_for_linking_query_excludes_note_id(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        a, _b, _c = self._seed(db_session, note_source_type)

        payload, status = _call(
            f"/notes/api/notes/search-for-linking?query=Python&exclude_note_id={a.id}",
            notes_routes.search_notes_for_linking,
        )

        assert status == 200
        ids = {n["id"] for n in payload["notes"]}
        assert a.id not in ids, "the note being edited was offered as a target"
        # ...and the OTHER Python note is still offered (so the exclusion is
        # scoped to one id, not "returned nothing").
        assert len(ids) == 1, payload
        titles = {n["title"] for n in payload["notes"]}
        assert titles == {"Python Advanced"}

    def test_search_for_linking_200_empty_on_blank_query(
        self, monkeypatch, db_session, note_source_type
    ):
        """A blank query short-circuits to an empty 200 without touching the
        service -- otherwise every keystroke-cleared autocomplete box runs a
        full unfiltered scan."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        service = MagicMock()
        monkeypatch.setattr(
            notes_routes, "NoteService", lambda username: service
        )

        payload, status = _call(
            "/notes/api/notes/search-for-linking?query=",
            notes_routes.search_notes_for_linking,
        )

        assert status == 200
        assert payload == {"success": True, "notes": []}
        service.search_notes_for_linking.assert_not_called()


class TestCollectionMembershipRouteStatusCodes:
    """add_to_collection / remove_from_collection return the same False for
    "note id missing / not a note" and "membership state wrong", so the routes
    must 404 a missing note BEFORE mapping False to the membership-specific
    409/404 messages. Pre-fix a stale note id got the factually wrong 409
    'Already in collection'.

    The branch pins the unknown-note 404 on add and the not-a-member 404 on
    remove; neither the genuine 409 nor remove's "Note not found" message has
    a successor.
    """

    def test_add_to_collection_409s_on_genuine_duplicate(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        collection = Collection(id=str(uuid.uuid4()), name="My Collection")
        db_session.add(collection)
        db_session.commit()
        db_session.add(
            DocumentCollection(
                document_id=note.id,
                collection_id=collection.id,
                indexed=False,
            )
        )
        db_session.commit()

        payload, status = _call(
            f"/notes/api/notes/{note.id}/collections",
            notes_routes.add_note_to_collection,
            note.id,
            method="POST",
            json={"collection_id": collection.id},
        )

        assert status == 409
        assert "already in collection" in payload["error"].lower()

    def test_remove_from_collection_404s_with_note_not_found_message(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        bogus_id = str(uuid.uuid4())
        collection_id = str(uuid.uuid4())

        payload, status = _call(
            f"/notes/api/notes/{bogus_id}/collections/{collection_id}",
            notes_routes.remove_note_from_collection,
            bogus_id,
            collection_id,
            method="DELETE",
        )

        assert status == 404
        # Pre-fix this was the misleading "Not in collection".
        assert "note not found" in payload["error"].lower()


class TestAIRoutes404OnUnknownNoteId:
    """research-questions / key-concepts / similar used to return 200 with
    empty results for a nonexistent note id (the AI service conflates a
    missing note with an empty one) -- indistinguishable from real-empty.

    The branch pins only ``/similar``; the two POST routes and the
    real-note positive control have no successor.
    """

    def _assert_404(self, monkeypatch, db_session, route_name, **call_kwargs):
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai_cls = MagicMock()
        monkeypatch.setattr(notes_routes, "NoteAIService", ai_cls)
        bogus_id = str(uuid.uuid4())

        payload, status = _call(
            f"/notes/api/notes/{bogus_id}/x",
            getattr(notes_routes, route_name),
            bogus_id,
            **call_kwargs,
        )

        assert status == 404
        assert "not found" in payload["error"].lower()
        # The guard must short-circuit BEFORE any AI/embedding work.
        ai_cls.assert_not_called()

    def test_research_questions_404s_on_unknown_id(
        self, monkeypatch, db_session, note_source_type
    ):
        self._assert_404(
            monkeypatch, db_session, "extract_research_questions", method="POST"
        )

    def test_key_concepts_404s_on_unknown_id(
        self, monkeypatch, db_session, note_source_type
    ):
        self._assert_404(
            monkeypatch, db_session, "extract_key_concepts", method="POST"
        )

    def test_similar_still_200s_for_existing_note(
        self, monkeypatch, db_session, note_source_type
    ):
        """Guard must not 404 valid notes -- the AI service result still
        flows through for a note that exists."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        ai = MagicMock()
        ai.find_similar_notes.return_value = []
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/similar",
            notes_routes.get_similar_notes,
            note.id,
        )

        assert status == 200
        assert payload["success"] is True
        assert payload["similar_notes"] == []


class TestSemanticSearchRouteClamps:
    """``semantic_search_notes`` clamps the client-supplied ``limit`` and
    ``min_similarity`` and 400s on non-numeric input before reaching the AI
    service. Without the clamp an attacker can pass limit=99999 ->
    fetch_k=limit*5 into FAISS (DoS); without the try/except a non-numeric
    value crashes to 500; without ``or None`` an empty collection_id would be
    passed as a real filter value.

    ``tests/web/test_pagination_clamping_census.py`` pins the ``limit`` clamp
    structurally. The ``min_similarity`` clamp (both ends), this route's
    ValueError->400 mapping, and the empty-collection_id coercion are pinned
    by nothing.
    """

    def _mock_ai(self, monkeypatch, notes_routes):
        ai = MagicMock()
        ai.semantic_search.return_value = []
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)
        return ai

    def test_limit_and_min_similarity_upper_clamped(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai = self._mock_ai(monkeypatch, notes_routes)

        payload, status = _call(
            "/notes/api/notes/semantic-search?q=foo&limit=99999&min_similarity=5.0",
            notes_routes.semantic_search_notes,
        )

        assert status == 200
        ai.semantic_search.assert_called_once()
        kwargs = ai.semantic_search.call_args.kwargs
        assert kwargs["limit"] == 200  # clamped from 99999
        assert kwargs["min_similarity"] == 1.0  # clamped from 5.0

    def test_limit_and_min_similarity_lower_clamped(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai = self._mock_ai(monkeypatch, notes_routes)

        payload, status = _call(
            "/notes/api/notes/semantic-search?q=foo&limit=0&min_similarity=-1",
            notes_routes.semantic_search_notes,
        )

        assert status == 200
        kwargs = ai.semantic_search.call_args.kwargs
        assert kwargs["limit"] == 1  # clamped up from 0
        assert kwargs["min_similarity"] == 0.0  # clamped up from -1

    def test_non_numeric_limit_400s_without_calling_service(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai = self._mock_ai(monkeypatch, notes_routes)

        payload, status = _call(
            "/notes/api/notes/semantic-search?q=foo&limit=banana",
            notes_routes.semantic_search_notes,
        )

        assert status == 400
        assert "invalid limit or min_similarity" in payload["error"].lower()
        ai.semantic_search.assert_not_called()

    def test_empty_collection_id_coerced_to_none(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai = self._mock_ai(monkeypatch, notes_routes)

        payload, status = _call(
            "/notes/api/notes/semantic-search?q=foo&collection_id=",
            notes_routes.semantic_search_notes,
        )

        assert status == 200
        kwargs = ai.semantic_search.call_args.kwargs
        assert kwargs["collection_id"] is None


class TestFactCheckNoteRoute:
    """``fact_check_note``: an empty claim list 422s with a fixed message
    BEFORE ``synthesize_factcheck_query`` runs; a non-empty list returns 200
    with both 'claims' and 'query'. The service methods are tested in
    test_note_ai_service.py but the route is not -- on either branch.
    """

    def test_no_claims_422_short_circuits_before_synthesize(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        ai = MagicMock()
        ai.extract_claims = AsyncMock(return_value=[])
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/fact-check",
            notes_routes.fact_check_note,
            note.id,
            method="POST",
        )

        assert status == 422
        assert payload["success"] is False
        assert (
            payload["error"]
            == "No checkable factual claims found in this note."
        )
        ai.synthesize_factcheck_query.assert_not_called()

    def test_claims_200_success_shape(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        ai = MagicMock()
        ai.extract_claims = AsyncMock(return_value=["claim one", "claim two"])
        ai.synthesize_factcheck_query.return_value = "verify claim one and two"
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/fact-check",
            notes_routes.fact_check_note,
            note.id,
            method="POST",
        )

        assert status == 200
        assert payload["success"] is True
        assert payload["claims"] == ["claim one", "claim two"]
        assert payload["query"] == "verify claim one and two"
        ai.synthesize_factcheck_query.assert_called_once_with(
            ["claim one", "claim two"]
        )


class TestUpdateNoteTriggersReindexOnTitleChange:
    """The service marks every ``DocumentCollection.indexed=False`` when the
    title OR content changes (the title is baked into chunk metadata at index
    time) and relies on the route firing the post-commit auto-index worker.
    Pre-fix a title-only PUT invalidated the rows but never scheduled the
    reindex, leaving the note un-indexed indefinitely.

    ``_trigger_note_auto_index`` appears in ZERO branch tests.
    """

    def test_title_only_update_triggers_auto_index(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        trigger = MagicMock()
        monkeypatch.setattr(notes_routes, "_trigger_note_auto_index", trigger)

        payload, status = _call(
            f"/notes/api/notes/{note.id}",
            notes_routes.update_note,
            note.id,
            method="PUT",
            json={"title": "Renamed"},
        )

        assert status == 200
        assert payload["success"] is True
        trigger.assert_called_once()
        assert trigger.call_args[0][0] == note.id

    def test_pinned_only_update_does_not_trigger_auto_index(
        self, monkeypatch, db_session, note_source_type
    ):
        """A favorite/pin flip never invalidates the index (the service only
        marks indexed=False for title/content changes), so the route must not
        schedule pointless reindex work for it."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        trigger = MagicMock()
        monkeypatch.setattr(notes_routes, "_trigger_note_auto_index", trigger)

        payload, status = _call(
            f"/notes/api/notes/{note.id}",
            notes_routes.update_note,
            note.id,
            method="PUT",
            json={"pinned": True},
        )

        assert status == 200
        assert payload["success"] is True
        trigger.assert_not_called()


class TestIndexNoteToCollectionRoute:
    """``index_note_to_collection`` is the only note route that hands the
    client id straight to the RAG service. It must (a) 400 a missing
    collection_id before any RAG work, (b) 404 an unknown note id BEFORE
    reaching ``get_rag_service`` (so an arbitrary user document can't be
    indexed through this path), and (c) map a RAG-service error result to a
    400 error contract, with a client-safe message, rather than letting it
    surface as a 500.

    The branch pins only the unknown-note 404 (via
    ``tests/security/test_two_user_attack_simulation.py``) and the
    ``force_reindex`` default.
    """

    def _patch_rag(self, monkeypatch, service_or_mock):
        monkeypatch.setattr(
            "local_deep_research.web.routers.rag.get_rag_service",
            service_or_mock,
        )

    def test_missing_collection_id_400s_before_rag(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        get_rag = MagicMock()
        self._patch_rag(monkeypatch, get_rag)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/index",
            notes_routes.index_note_to_collection,
            note.id,
            method="POST",
            json={},
        )

        assert status == 400
        assert "collection_id is required" in payload["error"].lower()
        get_rag.assert_not_called()

    def test_unknown_note_id_404s_before_rag(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        bogus_id = str(uuid.uuid4())
        # The note-existence guard must short-circuit BEFORE the RAG service
        # is constructed -- otherwise an arbitrary document id would be
        # indexed. Make get_rag_service explode if reached.
        get_rag = MagicMock(
            side_effect=AssertionError(
                "get_rag_service called before the note-existence guard"
            )
        )
        self._patch_rag(monkeypatch, get_rag)

        payload, status = _call(
            f"/notes/api/notes/{bogus_id}/index",
            notes_routes.index_note_to_collection,
            bogus_id,
            method="POST",
            json={"collection_id": str(uuid.uuid4())},
        )

        assert status == 404
        assert "not found" in payload["error"].lower()
        get_rag.assert_not_called()

    def test_valid_note_indexes_and_returns_result(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        collection_id = str(uuid.uuid4())

        rag_service = MagicMock()
        rag_service.__enter__.return_value = rag_service
        rag_service.index_document.return_value = {
            "status": "indexed",
            "chunks": 3,
        }
        self._patch_rag(monkeypatch, lambda request, username, cid: rag_service)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/index",
            notes_routes.index_note_to_collection,
            note.id,
            method="POST",
            json={"collection_id": collection_id, "force_reindex": True},
        )

        assert status == 200
        assert payload["success"] is True
        assert payload["result"]["status"] == "indexed"
        # The id forwarded to the RAG service is the verified note id.
        rag_service.index_document.assert_called_once_with(
            document_id=note.id,
            collection_id=collection_id,
            force_reindex=True,
        )
        rag_service.__exit__.assert_called_once_with(None, None, None)

    @pytest.mark.parametrize(
        ("service_error", "client_error"),
        [
            pytest.param(
                "embedding provider unavailable at "
                "http://embed-internal.corp.example:11434",
                "Indexing failed. Check the server logs for details.",
                id="arbitrary-service-text-is-withheld",
            ),
            pytest.param(
                "Document has no text content",
                "Document has no text content",
                id="known-document-guidance-passes",
            ),
            pytest.param(
                "Document deleted during indexing",
                "Document deleted during indexing",
                id="deleted-during-indexing-guidance-passes",
            ),
        ],
    )
    def test_rag_error_result_maps_to_400_not_500(
        self,
        monkeypatch,
        db_session,
        note_source_type,
        service_error,
        client_error,
    ):
        """A RAG-service result with status='error' is a handled failure --
        the route must return the route's 400 error contract, NOT let it fall
        through to a generic 500. Like the RAG document routes, it passes
        known document guidance and withholds any other service text."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)

        rag_service = MagicMock()
        rag_service.__enter__.return_value = rag_service
        rag_service.index_document.return_value = {
            "status": "error",
            "error": service_error,
        }
        self._patch_rag(monkeypatch, lambda request, username, cid: rag_service)

        payload, status = _call(
            f"/notes/api/notes/{note.id}/index",
            notes_routes.index_note_to_collection,
            note.id,
            method="POST",
            json={"collection_id": str(uuid.uuid4())},
        )

        assert status == 400
        assert payload["success"] is False
        assert payload["error"] == client_error
        rag_service.__exit__.assert_called_once_with(None, None, None)


class TestAcceptLinkRouteErrorMapping:
    """``accept_suggested_link`` RAISES on a real write failure instead of
    swallowing it into the same None its benign preconditions return. The
    route must map that ValueError to 400 (client-fixable) -- distinct from
    the 404 'Link could not be accepted' it returns for a None precondition
    -- rather than the generic 500 handle_api_error would otherwise produce.
    """

    def test_accept_link_maps_write_value_error_to_400(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)

        def _raise(self, note_id, target_note_id):
            raise ValueError("Content exceeds maximum length")

        monkeypatch.setattr(
            notes_routes.NoteService, "accept_suggested_link", _raise
        )

        payload, status = _call(
            f"/notes/api/notes/{note.id}/accept-link",
            notes_routes.accept_suggested_link,
            note.id,
            method="POST",
            json={"target_note_id": str(uuid.uuid4())},
        )

        assert status == 400
        assert payload["success"] is False
        # The route no longer forwards the service's ValueError text: the
        # same exception type can carry a filesystem path or SQL fragment
        # from deeper in the write path. The fixed message keeps the 400/404
        # distinction below meaningful without the detail.
        assert payload["error"] == "Suggested link cannot be accepted"
        assert "Content exceeds maximum length" not in payload["error"]

    def test_accept_link_404s_when_service_returns_none(
        self, monkeypatch, db_session, note_source_type
    ):
        """A benign precondition (service returns None) stays a 404 -- the
        two failure classes are distinguishable."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)

        monkeypatch.setattr(
            notes_routes.NoteService,
            "accept_suggested_link",
            lambda self, note_id, target_note_id: None,
        )

        payload, status = _call(
            f"/notes/api/notes/{note.id}/accept-link",
            notes_routes.accept_suggested_link,
            note.id,
            method="POST",
            json={"target_note_id": str(uuid.uuid4())},
        )

        assert status == 404
        assert payload["success"] is False


class TestNoteRoutesGuardUnknownId:
    """Routes that previously fell through to a 422/200 for a nonexistent
    note id now 404 -- matching every other note route's guard -- so a
    real-but-empty result is distinguishable from 'no such note'.

    ``backlinks`` / ``outgoing-links`` are already pinned by
    ``test_notes_router_fastapi.py``; the three below are not.
    """

    def test_fact_check_unknown_note_404s_before_extract(
        self, monkeypatch, db_session, note_source_type
    ):
        """The 404 fires before claim extraction, so the claim-less 422 is
        reserved for a note that genuinely exists."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        ai = MagicMock()
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)
        bogus = str(uuid.uuid4())

        payload, status = _call(
            f"/notes/api/notes/{bogus}/fact-check",
            notes_routes.fact_check_note,
            bogus,
            method="POST",
        )

        assert status == 404
        assert payload["success"] is False
        ai.extract_claims.assert_not_called()

    def test_unlinked_mentions_unknown_note_404s(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        bogus = str(uuid.uuid4())
        payload, status = _call(
            f"/notes/api/notes/{bogus}/unlinked-mentions",
            notes_routes.get_unlinked_mentions,
            bogus,
        )
        assert status == 404
        assert payload["success"] is False

    def test_reorder_research_unknown_note_404s(
        self, monkeypatch, db_session, note_source_type
    ):
        """Reorder previously returned 400 'research_ids do not match' for a
        deleted note (no NoteResearch rows -> empty set -> mismatch) instead
        of 404. It now 404s a missing note BEFORE the ids-match check, like
        its siblings, so a stale-id-after-delete race is reported
        correctly."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        bogus = str(uuid.uuid4())
        payload, status = _call(
            f"/notes/api/notes/{bogus}/research/reorder",
            notes_routes.reorder_note_research,
            bogus,
            method="POST",
            json={"research_ids": [str(uuid.uuid4())]},
        )
        assert status == 404
        assert payload["success"] is False
        assert "not found" in payload["error"].lower()

    def test_reorder_research_real_note_mismatch_still_400_positive_control(
        self, monkeypatch, db_session, note_source_type
    ):
        """The 404 guard must be specific to a MISSING note: a genuine note
        whose research_ids don't match its linked research still gets the 400
        mismatch error, not a spurious 404."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        payload, status = _call(
            f"/notes/api/notes/{note.id}/research/reorder",
            notes_routes.reorder_note_research,
            note.id,
            method="POST",
            json={"research_ids": [str(uuid.uuid4())]},
        )
        assert status == 400
        assert payload["success"] is False

    def test_backlinks_real_note_still_200_positive_control(
        self, monkeypatch, db_session, note_source_type
    ):
        """The guard must not reject a genuine note -- a real note with no
        backlinks still returns 200 with an empty list."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)
        payload, status = _call(
            f"/notes/api/notes/{note.id}/backlinks",
            notes_routes.get_backlinks,
            note.id,
        )
        assert status == 200
        assert payload["success"] is True
        assert payload["backlinks"] == []
        assert payload["total"] == 0


class TestSynthesisAndSuggestTagsInputValidation:
    """A non-string synthesis_type and an oversized existing_tags list get a
    clean 400, not an opaque 500 from deep in the AI service.

    ``tests/security/test_library_notes_authz_fastapi.py`` covers element
    TYPES inside these lists; the non-string ``synthesis_type`` (both routes)
    and the ``existing_tags`` SIZE cap are unpinned.
    """

    def test_preview_synthesis_400s_on_non_string_synthesis_type(
        self, monkeypatch, db_session, note_source_type
    ):
        # synthesize_notes does `synthesis_type not in {set}` (a hash) ->
        # TypeError -> 500 on a list. The route must 400 it first.
        notes_routes = _route_ctx(monkeypatch, db_session)
        payload, status = _call(
            "/notes/api/notes/synthesize/preview",
            notes_routes.preview_synthesis,
            method="POST",
            json={"note_ids": ["id1", "id2"], "synthesis_type": ["merge"]},
        )
        assert status == 400
        assert "synthesis_type" in payload["error"]

    def test_synthesize_400s_on_non_string_synthesis_type(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        payload, status = _call(
            "/notes/api/notes/synthesize",
            notes_routes.synthesize_notes,
            method="POST",
            json={"note_ids": ["id1", "id2"], "synthesis_type": {"x": 1}},
        )
        assert status == 400
        assert "synthesis_type" in payload["error"]

    def test_suggest_tags_400s_on_oversized_existing_tags(
        self, monkeypatch, db_session, note_source_type
    ):
        # 51 tags > MAX_TAGS_PER_NOTE (50): suggest_tags joins the WHOLE list
        # before truncating, so an uncapped list is a memory/CPU footgun.
        notes_routes = _route_ctx(monkeypatch, db_session)
        payload, status = _call(
            "/notes/api/notes/suggest-tags",
            notes_routes.suggest_tags,
            method="POST",
            json={"content": "x", "existing_tags": ["t"] * 51},
        )
        assert status == 400
        assert "existing_tags" in payload["error"]


class TestListNotesOffsetClamp:
    """An offset past the end of the filtered result set is clamped to
    ``total``; an in-range offset is untouched and really slices the page.

    ``tests/web/test_pagination_clamping_census.py`` covers the clamp, but on
    an EMPTY collection (``total == 0``) -- where ``offset = 0`` always would
    also pass. The in-range case and the real ``total`` are unpinned.
    """

    def test_offset_within_total_unchanged(
        self, monkeypatch, db_session, note_source_type
    ):
        notes_routes = _route_ctx(monkeypatch, db_session)
        for i in range(3):
            _seed_note(db_session, note_source_type, title=f"N{i}")

        payload, status = _call(
            "/notes/api/notes?offset=1&limit=10",
            notes_routes.list_notes,
        )

        assert status == 200
        assert payload["offset"] == 1  # in range -> untouched
        assert payload["total"] == 3
        assert len(payload["notes"]) == 2

    def test_total_is_the_whole_filtered_set_not_the_page(
        self, monkeypatch, db_session, note_source_type
    ):
        """``total`` must reflect the filtered set, not ``len(notes)`` --
        otherwise the page-N-of-M control always reads "1 of 1"."""
        notes_routes = _route_ctx(monkeypatch, db_session)
        for i in range(7):
            _seed_note(db_session, note_source_type, title=f"N{i}")

        payload, status = _call(
            "/notes/api/notes?offset=0&limit=3",
            notes_routes.list_notes,
        )

        assert status == 200
        assert len(payload["notes"]) == 3
        assert payload["total"] == 7


class TestSynthesizeRouteOrphanCleanup:
    """``synthesize_notes`` commits the new note in create_note's own session,
    THEN records the NoteSynthesis provenance in a second session. If that
    second persist fails, the route must roll back and delete the
    just-created note (so no orphaned 'synthesized' note is left behind),
    then surface the error as a 500. No successor on the branch.
    """

    def _mock_ai(self, monkeypatch, notes_routes):
        ai = MagicMock()
        ai.synthesize_notes = AsyncMock(
            return_value={
                "suggested_title": "Merged",
                "content": "merged body",
                "source_notes": [{"id": "src-1"}, {"id": "src-2"}],
                "truncated_sources": False,
            }
        )
        monkeypatch.setattr(notes_routes, "NoteAIService", lambda username: ai)

    def test_orphan_note_deleted_when_synthesis_record_fails(
        self, monkeypatch, db_session, note_source_type
    ):
        import local_deep_research.database.models as models

        notes_routes = _route_ctx(monkeypatch, db_session)
        self._mock_ai(monkeypatch, notes_routes)

        new_id = "new-note-id"
        delete_calls = []
        monkeypatch.setattr(
            notes_routes.NoteService, "create_note", lambda self, **kw: new_id
        )

        def _spy_delete(self, nid):
            delete_calls.append(nid)
            return True

        monkeypatch.setattr(
            notes_routes.NoteService, "delete_note", _spy_delete
        )

        # Force the synthesis-record persist to fail.
        def _boom(*a, **k):
            raise RuntimeError("synthesis insert failed")

        monkeypatch.setattr(models, "NoteSynthesis", _boom)

        payload, status = _call(
            "/notes/api/notes/synthesize",
            notes_routes.synthesize_notes,
            method="POST",
            json={
                "note_ids": ["src-1", "src-2"],
                "synthesis_type": "merge",
                "create_note": True,
            },
        )

        assert status == 500
        assert payload["success"] is False
        # The orphaned note was cleaned up exactly once with the new id.
        assert delete_calls == [new_id]

    def test_original_error_propagates_when_cleanup_delete_also_fails(
        self, monkeypatch, db_session, note_source_type
    ):
        import local_deep_research.database.models as models

        notes_routes = _route_ctx(monkeypatch, db_session)
        self._mock_ai(monkeypatch, notes_routes)

        monkeypatch.setattr(
            notes_routes.NoteService,
            "create_note",
            lambda self, **kw: "new-note-id",
        )

        def _delete_boom(self, nid):
            raise RuntimeError("delete failed too")

        monkeypatch.setattr(
            notes_routes.NoteService, "delete_note", _delete_boom
        )

        def _boom(*a, **k):
            raise RuntimeError("synthesis insert failed")

        monkeypatch.setattr(models, "NoteSynthesis", _boom)

        payload, status = _call(
            "/notes/api/notes/synthesize",
            notes_routes.synthesize_notes,
            method="POST",
            json={
                "note_ids": ["src-1"],
                "synthesis_type": "merge",
                "create_note": True,
            },
        )

        # The cleanup failure is swallowed (logged); the ORIGINAL synthesis
        # failure still surfaces as a 500.
        assert status == 500
        assert payload["success"] is False


class TestPatchNoteResearchRoute:
    """Route contract for ``patch_note_research`` (the NoteResearch
    is_collapsed toggle): 404 when the link doesn't exist, 200 when the
    toggle applies, and -- folded in from
    ``test_notes_api_validation_followups.py`` -- an OMITTED ``is_collapsed``
    passes through as ``None`` rather than being rejected.

    The branch pins only the non-bool 400.
    """

    def test_404_when_research_link_missing(self, monkeypatch, db_session):
        notes_routes = _route_ctx(monkeypatch, db_session)
        monkeypatch.setattr(
            notes_routes.NoteService,
            "update_note_research",
            lambda self, **kw: False,
        )
        payload, status = _call(
            "/notes/api/notes/n1/research/r1",
            notes_routes.patch_note_research,
            "n1",
            "r1",
            method="PATCH",
            json={"is_collapsed": True},
        )
        assert status == 404
        assert payload["success"] is False

    def test_200_on_successful_toggle(self, monkeypatch, db_session):
        notes_routes = _route_ctx(monkeypatch, db_session)
        captured = {}

        def _update(self, **kw):
            captured.update(kw)
            return True

        monkeypatch.setattr(
            notes_routes.NoteService, "update_note_research", _update
        )
        payload, status = _call(
            "/notes/api/notes/n1/research/r1",
            notes_routes.patch_note_research,
            "n1",
            "r1",
            method="PATCH",
            json={"is_collapsed": False},
        )
        assert status == 200
        assert payload["success"] is True
        assert captured["is_collapsed"] is False

    def test_patch_research_allows_omitted_is_collapsed(
        self, monkeypatch, db_session
    ):
        """The bool guard is written ``if "is_collapsed" in data and not
        isinstance(...)``. Written against ``.get()`` instead, an omitted key
        would be rejected as a non-bool ``None``. Ported from
        ``test_notes_api_validation_followups.py`` -- the branch ported the
        omitted-default controls for ``force_reindex`` and ``create_note``
        but not this one.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)
        captured = {}

        def _update(self, **kw):
            captured.update(kw)
            return True

        monkeypatch.setattr(
            notes_routes.NoteService, "update_note_research", _update
        )

        payload, status = _call(
            "/notes/api/notes/note-1/research/research-1",
            notes_routes.patch_note_research,
            "note-1",
            "research-1",
            method="PATCH",
            json={},
        )

        assert status == 200
        assert payload["success"] is True
        assert captured == {
            "note_id": "note-1",
            "research_id": "research-1",
            "is_collapsed": None,
        }


class TestGetSuggestedLinksRoute:
    """Route contract for ``get_suggested_links``: 400 on a non-numeric
    limit (the route's own try/except around ``_clamp_limit``), and a valid
    limit clamped into [1, 200] before reaching the service.
    """

    def test_400_on_invalid_limit(self, monkeypatch, db_session):
        notes_routes = _route_ctx(monkeypatch, db_session)
        payload, status = _call(
            "/notes/api/notes/n1/suggested-links?limit=abc",
            notes_routes.get_suggested_links,
            "n1",
        )
        assert status == 400
        assert "Invalid limit" in payload["error"]

    def test_success_clamps_limit_to_200(self, monkeypatch, db_session):
        notes_routes = _route_ctx(monkeypatch, db_session)
        captured = {}

        def _suggest(self, note_id, limit):
            captured["limit"] = limit
            return [{"id": "s1", "title": "Suggestion"}]

        monkeypatch.setattr(
            notes_routes.NoteAIService, "suggest_links", _suggest
        )
        # The route 404-guards an unknown note before suggesting; this test
        # exercises limit-clamping, so stub the note as present.
        monkeypatch.setattr(
            notes_routes.NoteService, "note_exists", lambda self, nid: True
        )
        payload, status = _call(
            "/notes/api/notes/n1/suggested-links?limit=999",
            notes_routes.get_suggested_links,
            "n1",
        )
        assert status == 200
        assert payload["suggestions"] == [{"id": "s1", "title": "Suggestion"}]
        assert captured["limit"] == 200  # clamped from 999


class TestAnnotationFieldTypeValidation:
    """``_validated_annotation_fields`` must reject non-string payload fields
    with ValueError (-> 400 at the route), not crash on ``.strip()`` with an
    opaque 500. The helper appears in ZERO branch tests.
    """

    def test_non_string_fields_raise_value_error(self):
        from local_deep_research.web.routers.notes import (
            _validated_annotation_fields,
        )

        for field in ("comment", "quote", "prefix", "suffix"):
            data = {"comment": "a comment", "quote": "a quote", field: 123}
            with pytest.raises(ValueError, match=f"{field} must be a string"):
                _validated_annotation_fields(data)

    def test_valid_payload_still_passes(self):
        from local_deep_research.web.routers.notes import (
            _validated_annotation_fields,
        )

        comment, quote, prefix, suffix = _validated_annotation_fields(
            {
                "comment": " c ",
                "quote": " q ",
                "prefix": "before",
                "suffix": "after",
            }
        )
        assert (comment, quote, prefix, suffix) == (
            "c",
            "q",
            "before",
            "after",
        )


class TestNotesBodySizeCap:
    """Only the surviving, portable half of main's ``TestNotesBodySizeCap``.

    The Flask ``arm_notes_body_cap`` / ``CSRFProtect`` ordering mechanism is
    gone; its FastAPI equivalents are pinned by
    ``tests/web/routers/test_merge_review_fixes.py`` (chunked 413),
    ``tests/web/test_remember_me_and_json_body_cap.py`` (middleware caps) and
    ``tests/web/routers/test_notes_body_gate_ordering.py`` (auth before the
    body gate). What none of them pins is the ROUTER constant's derivation:
    the notes cap is a memory bound expressed as a multiple of the content
    limit, not an independent magic number. A literal that drifts away from
    ``NOTE_CONTENT_MAX_BYTES`` starts 413-ing legitimate max-size notes whose
    JSON encoding is escape-dense.
    """

    def test_body_cap_is_two_times_the_note_content_limit(self):
        from local_deep_research.web.routers.notes import (
            _MAX_JSON_BODY_BYTES,
        )
        from local_deep_research.research_library.notes.services.note_service import (
            NOTE_CONTENT_MAX_BYTES,
        )

        assert _MAX_JSON_BODY_BYTES == 2 * NOTE_CONTENT_MAX_BYTES, (
            "the notes JSON body cap must stay a multiple of the note content "
            "limit -- it is a memory bound on the parse, not a second content "
            "limit"
        )

    def test_oversized_content_length_is_rejected_pre_parse(self):
        """A body that DECLARES an over-cap Content-Length is 413'd before a
        single byte is read.

        Successor of main's ``_reject_oversized_bodies`` test. The FastAPI
        equivalent is ``_notes_json_body``'s fast path; the ASGI ``receive``
        below raises if it is ever called, which is what makes this a
        *pre-parse* assertion rather than "it 413s eventually".
        ``test_remember_me_and_json_body_cap.py`` pins the middleware one
        layer up; the router dependency's own fast path is unpinned.
        """
        import asyncio

        from local_deep_research.web.routers.notes import (
            _MAX_JSON_BODY_BYTES,
            _notes_json_body,
        )

        async def _receive():  # pragma: no cover - must never run
            raise AssertionError(
                "the request body was read before the Content-Length check"
            )

        declared = str(_MAX_JSON_BODY_BYTES + 1).encode()
        request = Request(
            {
                "type": "http",
                "method": "POST",
                "path": "/notes/api/notes",
                "headers": [
                    (b"content-type", b"application/json"),
                    (b"content-length", declared),
                ],
                "session": {},
            },
            receive=_receive,
        )

        response = asyncio.run(_notes_json_body(request))

        assert isinstance(response, JSONResponse)
        assert response.status_code == 413
        assert "too large" in _json.loads(response.body)["error"].lower()

    def test_body_cap_admits_realistically_escaped_max_content(self):
        """The cap must admit a max-size note of REALISTIC prose (whose JSON
        escaping is near-1x), so ordinary content ``_assert_content_size``
        accepts is never 413'd here.

        Derived from a measured escape ratio on a concrete payload, so it
        cannot pass by restating how the constant is defined.
        """
        from local_deep_research.web.routers.notes import (
            _MAX_JSON_BODY_BYTES,
        )
        from local_deep_research.research_library.notes.services.note_service import (
            NOTE_CONTENT_MAX_BYTES,
        )

        # Realistic prose sample: ~2% newlines/quotes (denser than typical).
        sample = ("The quick brown fox jumps over the lazy dog. " * 20) + '\n"'
        body = _json.dumps({"title": "t", "content": sample, "tags": []})
        ratio = len(body.encode("utf-8")) / len(sample.encode("utf-8"))
        assert ratio * NOTE_CONTENT_MAX_BYTES < _MAX_JSON_BODY_BYTES

    def test_body_cap_is_a_memory_bound_not_a_second_content_limit(self):
        """The cap's real contract: bound pre-parse memory at 2x the content
        limit. It is deliberately NOT the precise content check -- that stays
        in ``_assert_content_size`` after parsing. Escape-dense content
        (control chars -> ``\\uXXXX``, ~6x) can exceed it and 413, which is
        the acknowledged trade."""
        from local_deep_research.web.routers.notes import (
            _MAX_JSON_BODY_BYTES,
        )
        from local_deep_research.research_library.notes.services.note_service import (
            NOTE_CONTENT_MAX_BYTES,
        )

        ctrl = "\x01"
        escaped_ratio = len(_json.dumps(ctrl)) - 2  # minus the two quotes
        assert escaped_ratio >= 6
        assert escaped_ratio * NOTE_CONTENT_MAX_BYTES > _MAX_JSON_BODY_BYTES


class TestFixedErrorMessagesAreTrueAndComplete:
    """The flattened 4xx messages on ``web/routers/notes.py``.

    Two properties, both of which a revert breaks:

    * the message must be TRUE for the branch that produced it -- a fixed
      string is worse than an exception echo if it misreports the cause;
    * the exception's own text must not appear in the body, since the same
      ``ValueError`` type is raised from service and validator layers that
      can carry a filesystem path, a SQL fragment or a note's content.

    Each test names the specific revert it catches.
    """

    # -- resolve_link: the two ValueErrors of _clamp_text_query -------------

    def test_non_string_link_text_is_not_reported_as_a_length_problem(
        self, monkeypatch, db_session
    ):
        """``_clamp_text_query`` raises for a non-string OR an over-long
        value, and ``resolve_link`` is the only caller whose input is not a
        query param -- ``_NotesBody`` is an uncoerced parsed-JSON dict.

        Catches the revert to a single hardcoded "exceeds maximum length"
        message for both branches, which answered
        ``{"link_text": 123}`` with a factually false 400 telling the user
        their 3-character value was over a 500-character cap.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)

        payload, status = _call(
            "/notes/api/notes/resolve-link",
            notes_routes.resolve_link,
            method="POST",
            json={"link_text": 123},
        )

        assert status == 400
        assert payload["success"] is False
        assert payload["error"] == "link_text must be a string"
        assert "maximum length" not in payload["error"]

    def test_over_long_link_text_still_reports_the_length_cap(
        self, monkeypatch, db_session
    ):
        """Non-vacuity control for the test above: the length branch is
        still reachable and still names the cap, so the type check did not
        simply swallow both cases into one message.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)

        payload, status = _call(
            "/notes/api/notes/resolve-link",
            notes_routes.resolve_link,
            method="POST",
            json={"link_text": "x" * 501},
        )

        assert status == 400
        assert payload["error"] == (
            "link_text exceeds maximum length (500 chars)"
        )

    # -- link_research_to_note ---------------------------------------------

    def test_link_research_value_error_returns_the_fixed_message(
        self, monkeypatch, db_session, note_source_type
    ):
        """Catches the revert of ``link_research_to_note``'s
        ``except ValueError`` arm to ``{"error": str(e)}``. The service
        raises this from the research-per-note cap check, but the same
        handler catches every other ``ValueError`` raised under
        ``NoteService.link_research_to_note`` -- including ones from the
        note-content and session layers below it.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)

        def _raise(self, note_id, research_id):
            raise ValueError(
                "private validation detail /srv/ldr-data/victim.db"
            )

        monkeypatch.setattr(
            notes_routes.NoteService, "link_research_to_note", _raise
        )

        payload, status = _call(
            f"/notes/api/notes/{note.id}/research",
            notes_routes.link_research_to_note,
            note.id,
            method="POST",
            json={"research_id": str(uuid.uuid4())},
        )

        assert status == 400
        assert payload["success"] is False
        assert payload["error"] == "Research cannot be linked to this note"
        assert "private validation detail" not in payload["error"]
        assert "/srv/ldr-data" not in payload["error"]

    def test_link_research_to_unknown_note_is_still_404(
        self, monkeypatch, db_session, note_source_type
    ):
        """The 404 for a missing note must survive the message flattening.

        Before the flattening, this route recovered the 404 by matching
        ``"not found" in str(e).lower()`` on the service's ``ValueError``.
        With the text no longer read, two ``note_exists`` calls keep a
        missing note out of the sibling 400: a pre-check before the service
        call, and a re-check in the ``except ValueError`` arm for a note
        deleted in between. Delete both and this test goes red while every
        other assertion in this class stays green.

        The status assertion alone would survive deleting the PRE-check (the
        re-check would answer 404 too), so this also asserts the service was
        never reached -- that is the leg that pins the pre-check specifically.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)

        service_calls = []

        def _raise(self, note_id, research_id):
            service_calls.append(note_id)
            raise ValueError(f"Note {note_id} not found")

        monkeypatch.setattr(
            notes_routes.NoteService, "link_research_to_note", _raise
        )

        missing_note_id = str(uuid.uuid4())
        payload, status = _call(
            f"/notes/api/notes/{missing_note_id}/research",
            notes_routes.link_research_to_note,
            missing_note_id,
            method="POST",
            json={"research_id": str(uuid.uuid4())},
        )

        assert status == 404, payload
        assert payload["error"] == "Note not found"
        assert missing_note_id not in payload["error"]
        assert service_calls == [], (
            "an already-missing note must 404 from the pre-check, before "
            "the service runs"
        )

    def test_link_research_note_deleted_mid_call_is_404_not_400(
        self, monkeypatch, db_session, note_source_type
    ):
        """TOCTOU: the note is deleted between the pre-check and the call.

        The pre-check sees the note, the service then raises because the row
        is gone. Without the re-check in the ``except ValueError`` arm the
        client gets 400 "Research cannot be linked to this note" for what is
        really a 404 -- the same misclassification the pre-check exists to
        prevent, just one instant later. ``note_exists`` is answered True
        then False to stage exactly that interleaving; removing the re-check
        turns this into a 400.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)

        answers = [True, False]

        def _exists(self, note_id):
            return answers.pop(0)

        def _raise(self, note_id, research_id):
            raise ValueError(f"Note {note_id} not found")

        monkeypatch.setattr(notes_routes.NoteService, "note_exists", _exists)
        monkeypatch.setattr(
            notes_routes.NoteService, "link_research_to_note", _raise
        )

        note_id = str(uuid.uuid4())
        payload, status = _call(
            f"/notes/api/notes/{note_id}/research",
            notes_routes.link_research_to_note,
            note_id,
            method="POST",
            json={"research_id": str(uuid.uuid4())},
        )

        assert status == 404, payload
        assert payload["error"] == "Note not found"
        assert answers == [], (
            "both note_exists calls must have run (pre-check, then re-check)"
        )

    # -- remove_note_from_collection ---------------------------------------

    def test_remove_from_collection_value_error_returns_fixed_message(
        self, monkeypatch, db_session, note_source_type
    ):
        """Catches the revert of ``remove_note_from_collection``'s
        ``except ValueError`` arm to ``{"error": str(e)}``. The guard it
        reports is "you cannot unlink a note from the system Notes
        collection", but the handler wraps the whole service call.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)
        note = _seed_note(db_session, note_source_type)

        def _raise(self, note_id, collection_id):
            raise ValueError("private guard detail /srv/ldr-data/victim.db")

        monkeypatch.setattr(
            notes_routes.NoteService, "remove_from_collection", _raise
        )

        payload, status = _call(
            f"/notes/api/notes/{note.id}/collections/{uuid.uuid4()}",
            notes_routes.remove_note_from_collection,
            note.id,
            str(uuid.uuid4()),
            method="DELETE",
        )

        assert status == 400
        assert payload["success"] is False
        assert payload["error"] == (
            "Note cannot be removed from this collection"
        )
        assert "private guard detail" not in payload["error"]
        assert "/srv/ldr-data" not in payload["error"]

    # -- create_research_annotation ----------------------------------------

    def test_annotation_validation_error_returns_fixed_message(
        self, monkeypatch, db_session
    ):
        """Catches the revert of ``create_research_annotation``'s
        ``except ValueError`` arm to ``{"error": str(e)}``.

        The branch is driven through the real validator
        (``_validated_annotation_fields``), so this also pins that the
        rejection still happens BEFORE the research-existence lookup -- a
        400, not the 404 a missing research id would give.
        """
        notes_routes = _route_ctx(monkeypatch, db_session)

        payload, status = _call(
            f"/notes/api/research/{uuid.uuid4()}/annotations",
            notes_routes.create_research_annotation,
            str(uuid.uuid4()),
            method="POST",
            json={"quote": "only a quote"},
        )

        assert status == 400, payload
        assert payload["success"] is False
        assert payload["error"] == "Invalid annotation data"
        assert "comment is required" not in payload["error"]