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.

138 KB
Raw Blame
"""
Notes Routes - API endpoints and pages for the notes feature (FastAPI).

Ported from the Flask ``web/routes/notes_routes.py`` blueprint (``notes_bp``,
url_prefix ``/notes``). Every endpoint preserves the same paths, methods,
and service calls. Three deliberate divergences from the Flask blueprint:

  * error responses use fixed client-safe messages rather than
    exception-derived detail;
  * ``link_research_to_note`` checks that the note exists both before
    calling the service and again when the service raises (the Flask route
    recovered that 404 by matching "not found" in the exception text, which
    the fixed messages no longer allow; the second check covers a note
    deleted between the first check and the call);
  * the nine LLM-backed AI routes classify an unconfigured LLM separately
    from an invalid request and from a server fault -- 400 with
    ``error_type: model_not_configured`` via
    ``_llm_not_configured_response``, where Flask answered a generic 500
    (and, on ``suggest-tags``, a request-validation 400).

Notes on the port:
  * ``@login_required`` → ``Depends(require_auth)``; the per-route manual
    ``session.get("username")`` / 401 guard is dropped because ``require_auth``
    already raises 401 when there is no authenticated user.
  * The two blueprint-wide ``before_request`` hooks (``_reject_oversized_bodies``
    and ``_reject_non_object_json_body``) are collapsed into the shared
    ``_notes_json_body`` dependency, injected into every mutating route.
  * Flask ``request.args`` → ``request.query_params``; ``session[...]`` →
    the ``username`` dependency / ``request.session``.
  * Route registration order is deliberate: the literal ``/api/notes/...`` GET
    routes are registered BEFORE ``GET /api/notes/{note_id}`` because Starlette
    matches routes in registration order (Flask's map gave static rules
    priority automatically; FastAPI does not).
"""

import asyncio
import builtins
import itertools
import json
import math
import reprlib

from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse
from loguru import logger
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import load_only

from ...config.llm_config import (
    LLM_NOT_CONFIGURED_CLIENT_MESSAGE,
    LLMNotConfiguredError,
)
from ...research_library.notes.services.note_ai_service import NoteAIService
from ...research_library.notes.services.note_service import (
    MAX_TAG_LENGTH,
    MAX_TAGS_PER_NOTE,
    NOTE_CONTENT_MAX_BYTES,
    NoteService,
    _assert_content_size,
    escape_markdown_link_label,
)
from ...research_library.utils import handle_api_error
from ...security.data_sanitizer import REDACTION_TEXT
from ...security.log_sanitizer import (
    _LOG_REDACTION_MAX_CHARS,
    _is_empty_log_value,
    _is_sensitive_log_key,
    _truncate_for_log_redaction,
    redact_for_log,
)
from ..dependencies.auth import require_auth
from ..dependencies.json_body import is_json_request
from ..dependencies.rate_limit import async_shared_limit, limiter, _user_key
from ..dependencies.threadpool import run_db_sync
from ..template_config import templates

# Cap on user-supplied free-text query params that flow into `ILIKE %...%`
# over unbounded TEXT columns — shared with unified_search_routes via
# _search_constants so the two route modules can't diverge. The router lives
# in web/routers/, so reach the file in web/routes/.
from ..routes._search_constants import MAX_SEARCH_LEN
from typing import Annotated, Any

# Bound at import time (not looked up on the class at call time) because
# tests monkeypatch the ``NoteAIService`` name in this module.
_MAX_GRADE_SOURCES = NoteAIService.MAX_GRADE_SOURCES

MAX_LINK_TEXT_LEN = 500
# Per-claim length cap for the fact-check grade endpoint (claims are free text
# from the client; the grader bounds the count but not the per-string size).
MAX_CLAIM_LEN = 1000
# Upper bound on any ?limit query param across the list/search endpoints
# (was an unnamed 200 repeated at six call sites).
MAX_LIMIT = 200


def _clamp_limit(request: Request, default, max_=MAX_LIMIT):
    """Parse ``?limit`` into ``[1, max_]``, defaulting to ``default``.

    Raises ``ValueError`` on a non-integer value; the caller wraps this in
    ``try`` and returns the 400 (matching the six former inline copies).
    """
    return max(1, min(int(request.query_params.get("limit", default)), max_))


def _clamp_text_query(value, name, max_len=MAX_SEARCH_LEN):
    """Return value or raise ValueError if it exceeds the cap.

    ``None``/empty pass through unchanged so optional params behave the
    same as before. The caller maps the failure to a fixed 400 response.

    Two distinct failures share the ``ValueError``: a non-string value and
    an over-length one. A caller that passes ``request.query_params.get(...)``
    can only ever hit the length branch (Starlette's query params are always
    ``str``), so a single fixed length message is truthful there. A caller
    reading a JSON body must decide by type BEFORE calling this — see
    ``resolve_link`` — because the body is an uncoerced ``dict``.

    That makes the non-string branch DEAD at every current call site (three
    query-param readers plus ``resolve_link``, which type-checks first). It
    is kept as a defensive guard, not as live behaviour: without it a future
    caller that forgets the type check would reach ``len(value)`` and raise
    ``TypeError``, which no caller here catches, turning a bad body into a
    500 instead of a 400. Any new call site that can pass a non-string must
    still do its own type check so its fixed message stays truthful.
    """
    if value is None:
        return value
    if not isinstance(value, str):
        raise ValueError(f"{name} must be a string")
    if len(value) > max_len:
        raise ValueError(f"{name} exceeds maximum length ({max_len} chars)")
    return value


# Bounded repr for an untrusted value going into an audit-log line. A naive
# ``repr(value)[:100]`` slices AFTER building the full repr — for a value
# that came out of ``_notes_json_body`` (up to the 100 MB notes JSON body
# cap, see ``_MAX_JSON_BODY_BYTES`` above) that means materializing a second
# ~100 MB+ string (more if it's escape-heavy, since ``repr`` expands each
# control char to ``\xNN``) just to throw all but 100 chars away. Same
# problem for a huge list/dict: ``repr()`` walks and stringifies every
# element before any truncation happens.
#
# ``reprlib.Repr`` avoids this for STRINGS and LISTS/TUPLES only: its
# ``repr_str`` slices, and ``repr_list``/``repr_tuple`` ``itertools.islice``,
# BEFORE recursing/stringifying (see ``reprlib.Repr.repr_str`` /
# ``repr_list`` in the stdlib), so those costs are bounded by the limits
# below regardless of the input's real size. It does NOT hold for
# dict/set/frozenset: ``repr_dict`` / ``repr_set`` / ``repr_frozenset``
# call ``reprlib._possibly_sorted()`` — a plain ``sorted()`` over the FULL
# container — and slice to ``maxdict``/``maxset``/``maxfrozenset`` only
# afterwards. That is why values reach ``reprlib`` here only through the
# bounded walk in ``_bound_dict_shaped_walk`` below. ``maxlevel`` also caps
# recursion depth for a deeply nested dict.
#
# Redaction runs BEFORE any cut. ``repr_str`` keeps a long string's first
# and last ~48 characters and drops the middle; the final ``[:100]``
# backstop below keeps only a prefix. Either cut can drop a credential's
# label (``?key=``, ``api_key=``, the ``user:`` ... ``@`` around URL
# userinfo) while keeping part of the secret, and the loguru patcher's
# redaction — the backstop for every sink — then has nothing to match. The
# value was often logged in full before it went through this preview, so
# the patcher used to see the whole thing. ``_RedactingRepr`` therefore runs
# the patcher's own redaction (``redact_for_log``) on every string, and on
# every ``builtins.repr`` text ``repr_instance`` falls back to, before
# reprlib shortens it; ``_bound_dict_shaped_walk`` masks a value under a
# sensitive key name (``api_key``, ``password``, ...), as the patcher's
# ``extra`` redaction does, because per-string redaction cannot see a label
# that lives in the dict key (and masks the value under any key its
# key-check budget cannot cover, see ``_PREVIEW_KEY_CHECK_BUDGET``).
#
# Redaction costs about 2 microseconds per character on adversarial input
# (a run of spaces, or of ``https://a:b@ ``): ~70-120 ms for a 32 KiB
# string, where the unredacted preview cost well under 0.1 ms. The preview
# shows at most 100 characters, so each string is redacted only up to
# ``_PREVIEW_STRING_REDACTION_MAX_CHARS``: it is cut first by the
# patcher's own rule (``_truncate_for_log_redaction`` with that bound,
# only at a whitespace boundary, dropping the whole run the bound falls
# in), the kept head is redacted, and the rest is replaced by the
# omitted-length marker. A credential token holds no boundary character,
# so the head never keeps part of a token whose label or ``@`` lies past
# the cut, and nothing past the cut is shown. A bounded container can
# still hold over twenty thousand strings (reprlib renders up to ten keys
# and ten values per dict at each of four levels), so each preview also
# has a total redaction budget of ``_PREVIEW_REDACTION_BUDGET``
# characters. Each redaction also has a fixed cost of about 25
# microseconds however short the string, so every call is charged at
# least ``_PREVIEW_REDACTION_MIN_CHARGE`` characters: a preview runs at
# most ``_PREVIEW_REDACTION_BUDGET // _PREVIEW_REDACTION_MIN_CHARGE``
# (32) redactions over at most ``_PREVIEW_REDACTION_BUDGET`` characters
# in total, a few milliseconds at worst. The 100-character preview shows
# only the first few strings reprlib renders, and those are the ones
# redacted first. A string that does not fit the remaining budget is
# shown as ``<N-char string not shown>``, never raw.
_PREVIEW_STRING_REDACTION_MAX_CHARS = 512
_PREVIEW_REDACTION_BUDGET = 1_024
_PREVIEW_REDACTION_MIN_CHARGE = 32


class _RedactingRepr(reprlib.Repr):
    """``reprlib.Repr`` that redacts each string before shortening it.

    Stateful (the remaining budget), so ``_log_value_preview`` builds a new
    one per call; the module-level ``_log_value_repr`` instance only holds
    the shared limits.
    """

    def __init__(self) -> None:
        super().__init__(
            maxlevel=4,
            maxtuple=10,
            maxlist=10,
            maxdict=10,
            maxset=10,
            maxfrozenset=10,
            maxstring=100,
            maxlong=100,
            maxother=100,
        )
        self._budget = _PREVIEW_REDACTION_BUDGET

    def _redacted(self, text: str):
        cost = max(
            min(len(text), _PREVIEW_STRING_REDACTION_MAX_CHARS),
            _PREVIEW_REDACTION_MIN_CHARGE,
        )
        if cost > self._budget:
            return None
        self._budget -= cost
        head, marker = _truncate_for_log_redaction(
            text, _PREVIEW_STRING_REDACTION_MAX_CHARS
        )
        return redact_for_log(head) + marker

    def repr_str(self, x, level):
        redacted = self._redacted(x)
        if redacted is None:
            return f"<{len(x)}-char string not shown>"
        return super().repr_str(redacted, level)

    def repr_instance(self, x, level):
        try:
            text = builtins.repr(x)
        except Exception:
            return f"<{x.__class__.__name__} instance at {id(x):#x}>"
        redacted = self._redacted(text)
        if redacted is None:
            return f"<{x.__class__.__name__} repr not shown>"
        if len(redacted) > self.maxother:
            i = max(0, (self.maxother - 3) // 2)
            j = max(0, self.maxother - 3 - i)
            redacted = (
                redacted[:i] + self.fillvalue + redacted[len(redacted) - j :]
            )
        return redacted


_log_value_repr = _RedactingRepr()


def _log_value_preview(value: Any) -> str:
    """Bounded, ``logger.warning``-safe preview of an untrusted JSON value.

    Use in place of ``repr(value)[:100]`` at any audit-log site whose value
    comes from request input (query params, and especially JSON bodies,
    which this router allows up to ~100 MB). See ``_log_value_repr`` above
    for why plain ``repr()[:100]`` is unsafe here.

    ``value`` is pre-bounded by ``_bound_dict_shaped_walk`` before it
    reaches ``reprlib`` — see that function for why reprlib's own limits do
    not bound dict/set/frozenset cost on their own.

    The final bound is a cheap backstop, not the primary defense — the
    limits on ``_log_value_repr`` plus the pre-bounding step already keep
    the *work* bounded; this just keeps the *output* bounded too (a
    container's ten per-element reprs, plus reprlib's own ``...`` marker,
    can still sum past 100 chars). But the backstop must not slice
    truncation *markers* off with the content, and it must keep the two
    truncation conditions distinguishable. When it truncates, the preview
    gets one of exactly two endings, each carrying its own meaning:

    * an items-omitted tail — ``', ...}'``, ``', ...]'`` or ``', ...)'``:
      ENTRIES were dropped from some container (it held strictly more
      than ``reprlib``'s per-container limit of 10). A repr that already
      ends in one of ``reprlib``'s own container tails keeps it inside
      the cap; a repr whose dropped entries are NESTED — the tail sits
      inside the repr, followed by the outer container's closing
      delimiters, so it is not the suffix of the whole repr and the
      tail check cannot see it — instead gets
      ``_PREVIEW_ITEMS_OMITTED_TAIL`` appended, guided by the
      ``items_omitted`` flag the pre-bounding walk reports.
    * a bare ``...`` (``_PREVIEW_ELLIPSIS``): LENGTH-only truncation —
      no visited container lost entries; the repr simply exceeded the
      char cap.

    The two endings differ in their final character and so can never be
    byte-equal: an 11-key (or 50,010-key) payload nested anywhere the
    pre-bounding walk visits always previews differently from the
    corresponding all-≤10-key payload. Reprs that fit the cap are
    returned untouched, and the preview never exceeds the cap.

    Every string (and every ``repr`` text of a non-container object) has
    already been through the log patcher's credential redaction before
    ``reprlib`` or the backstop shortens it, and a value under a sensitive
    dict key (or under a key the key-check budget could not cover) is
    masked whole — see ``_RedactingRepr`` above. A cut
    therefore only removes text the patcher already redacted or would
    leave as is: it cannot strip a recognised credential's label while
    keeping part of the secret.
    """
    bounded, items_omitted = _bound_dict_shaped_walk(value, 0)
    text = _RedactingRepr().repr(bounded)
    if len(text) <= _PREVIEW_MAX_CHARS:
        return text
    for tail in _PREVIEW_CONTAINER_TAILS:
        if text.endswith(tail):
            return text[: _PREVIEW_MAX_CHARS - len(tail)] + tail
    if items_omitted:
        return (
            text[: _PREVIEW_MAX_CHARS - len(_PREVIEW_ITEMS_OMITTED_TAIL)]
            + _PREVIEW_ITEMS_OMITTED_TAIL
        )
    return (
        text[: _PREVIEW_MAX_CHARS - len(_PREVIEW_ELLIPSIS)] + _PREVIEW_ELLIPSIS
    )


# One MORE than ``_log_value_repr``'s own maxdict/maxlist/maxset/maxtuple
# (10), deliberately. reprlib only appends its ``...`` truncation marker
# when the container handed to it is STRICTLY longer than that limit (``if
# n > self.maxdict: pieces.append(self.fillvalue)``). Pre-truncating to
# exactly 10 would make an attacker's 400,000-key body render byte-identical
# to a legitimate 10-key one — silently erasing "there was more" from the
# audit line, which is the one thing this log site exists to record. Keeping
# 11 costs nothing (reprlib discards the 11th) and restores the marker.
# ``_PREVIEW_MAX_DEPTH`` matches ``_log_value_repr``'s ``maxlevel``.
_PREVIEW_MAX_ITEMS = 11
_PREVIEW_MAX_DEPTH = 4
# Final output cap for ``_log_value_preview`` (previously an inline
# ``[:100]`` slice).
_PREVIEW_MAX_CHARS = 100
# Matches reprlib's ``fillvalue`` and the ``...`` marker convention used
# throughout this module.
_PREVIEW_ELLIPSIS = "..."
# reprlib's "the container had more items than I showed" tails — its ``...``
# fillvalue joined onto the container's closing bracket. When the final
# char bound bites, preserving the tail keeps an item-bounded payload (e.g.
# a 50,010-key dict whose first ten ~100-char values fill the cap on their
# own) distinguishable from a merely char-bounded one, instead of slicing
# the marker off entirely.
_PREVIEW_CONTAINER_TAILS = (", ...}", ", ...]", ", ...)")
# The nested counterpart to the tails above. When the pre-bounding walk
# reports that some container it visited held more entries than
# ``reprlib``'s per-container limit (so entries were dropped) but the
# ``reprlib`` fill sits INSIDE the repr — followed by the outer
# container's closing delimiters, not at the very end — the tail check
# in ``_log_value_preview`` cannot preserve it. Appending this explicit
# tail keeps such a payload (e.g. ``{"outer": {<11 keys with ~100-char
# values>}}``) byte-distinguishable from the corresponding all-≤10-key
# payload, whose only truncation is the char cap and which therefore
# ends in a bare ``...``. Deliberately identical to the dict tail: both
# spell "entries were omitted".
_PREVIEW_ITEMS_OMITTED_TAIL = ", ...}"
# Budget for the sensitive-key check in ``_bound_dict_shaped_walk``. The
# check walks the whole key (``DataSanitizer.is_sensitive_setting``
# normalises it character by character), JSON keys have no length limit,
# and the walk can visit over sixteen thousand keys (up to 11 per dict in
# up to 1,464 dicts). Each check of a str key is charged the key's length,
# at least ``_PREVIEW_KEY_CHECK_MIN_CHARGE`` (a non-str key is never
# sensitive, and its check is free), so one preview checks at most
# ``_PREVIEW_KEY_CHECK_BUDGET`` characters of keys in at most 512 checks.
# A key the remaining budget cannot cover is not checked, and its value is
# masked as if the key were sensitive (fail closed).
_PREVIEW_KEY_CHECK_BUDGET = _LOG_REDACTION_MAX_CHARS
_PREVIEW_KEY_CHECK_MIN_CHARGE = 64


def _bound_dict_shaped_walk(
    value: Any, _depth: int, _key_budget: list[int] | None = None
) -> tuple[Any, bool]:
    """Return a size-bounded copy of ``value``, safe to hand to
    ``_log_value_repr.repr()``, plus an "entries were dropped" flag.

    ``reprlib.Repr`` bounds *string* and *list/tuple* reprs by slicing
    BEFORE recursing (see ``repr_str`` / ``repr_list`` in the stdlib), so
    those are already O(1) regardless of input size — the module comment
    above relies on that. But ``repr_dict`` / ``repr_set`` /
    ``repr_frozenset`` call stdlib ``reprlib._possibly_sorted()`` — which is
    a plain ``sorted(x)`` over the FULL container — and only slice to
    ``maxdict``/``maxset``/``maxfrozenset`` afterwards. For a dict/set built
    from a large attacker-controlled JSON body (this router allows up to
    ~100 MB, e.g. ``{"is_collapsed": {<N keys>}}`` reaching
    ``patch_note_research``) that reintroduces the exact O(N log N) time /
    O(N) memory cost ``_log_value_repr`` exists to eliminate — measured at
    ~10-22 ms for a 400k-entry dict/set on py3.14, scaling linearly, versus
    ~0 ms for an equivalently large string or list through the same helper.

    Fix: truncate every dict/set/frozenset to ``_PREVIEW_MAX_ITEMS`` entries
    OURSELVES — via ``itertools.islice`` over the container's natural
    iteration order (insertion order for dicts, arbitrary-but-cheap for
    sets), never ``sorted()`` — before reprlib ever sees it. Once bounded
    this way, reprlib's own ``repr_dict``/``repr_set`` still calls
    ``sorted()``, but over at most ``_PREVIEW_MAX_ITEMS`` items, which is
    negligible.

    Recurses into dict values and list/tuple elements (only the first
    ``_PREVIEW_MAX_ITEMS`` of each, mirroring reprlib's own slicing) up to
    ``_PREVIEW_MAX_DEPTH`` — matching ``_log_value_repr``'s ``maxlevel`` —
    so a large dict/set nested a few levels down (e.g. inside a list inside
    a dict) is bounded too, not just one sitting at the top level. The
    number of containers copied is the geometric sum
    ``1 + M + M**2 + M**3`` for ``M = _PREVIEW_MAX_ITEMS`` (1,464 at the
    current limits), NOT ``M ** _PREVIEW_MAX_DEPTH``, regardless of the real
    structure's size. Dict/set *keys* are returned unbounded: JSON object
    keys are always strings, and rendering a huge key is bounded by
    ``_RedactingRepr``'s redaction budget and ``repr_str`` slicing. The
    sensitive-key check on each visited dict key is NOT free — it walks the
    whole key — so it draws on a per-preview budget,
    ``_PREVIEW_KEY_CHECK_BUDGET`` (``_key_budget`` holds what remains; the
    outermost call creates it). A key the remaining budget cannot cover is
    not checked and its value is masked whole, as for a sensitive key. The
    walk still descends into that masked value (with no budget, so every
    key under it is masked unchecked) to compute the items-omitted flag.

    Past ``_PREVIEW_MAX_DEPTH`` the walk stops and the sub-value is handed
    to reprlib untouched. For a **dict** that costs nothing: ``repr_dict``
    checks ``level <= 0`` *before* calling ``_possibly_sorted``, so an
    over-deep dict collapses to ``{...}`` unsorted. It is NOT free for a
    **set/frozenset**: ``repr_set``/``repr_frozenset`` call
    ``_possibly_sorted`` at the top of the method, *before*
    ``_repr_iterable`` gets to check ``level``, so a huge set nested past
    the cap is still sorted in full and the result thrown away (measured
    ~13 ms for ``[[[[set(range(400_000))]]]]``, output ``[[[[{...}]]]]``).
    Likewise, set/frozenset *elements* are never recursed into, so a
    container inside a set — a frozenset or tuple, the only hashable
    candidates — stays unbounded at any depth (~13 ms for
    ``{frozenset(range(400_000))}``). Neither shape is reachable from this
    router (JSON has no set literal), but both matter if this helper is
    reused elsewhere.

    Values that are not dict/set/frozenset/list/tuple (str, int, float,
    bool, None) pass through unchanged — reprlib's ``maxstring`` /
    ``maxlong`` bound those. ``maxlong`` only slices an ALREADY-built
    string, though: ``reprlib.repr_int`` calls ``builtins.repr(x)`` in full
    before truncating, so a huge ``int`` is the one JSON-native type whose
    repr cost this helper does not bound (measured ~2 s for a 2,000,000-
    digit int). It is unreachable from this router only because
    ``json.loads`` refuses an integer literal longer than
    ``sys.get_int_max_str_digits()`` (4300 by default). Nor does the
    pass-through extend to an arbitrary object: reprlib has no per-type
    method for a custom class, so it falls through to ``repr_instance``,
    which calls ``builtins.repr(x)`` in FULL and ignores ``level``
    entirely — a hostile ``__repr__`` can allocate whatever it likes
    (measured ~170 ms / 200 MB) before reprlib truncates the resulting
    string. Nothing here bounds that. It is unreachable at this router's
    call sites, whose values all come out of ``json.loads`` and so can only
    be JSON-native types, but any reuse of this helper at a call site
    logging a non-JSON-sourced value must account for it.

    Returns ``(bounded_value, items_omitted)``. ``items_omitted`` is True
    iff any dict/set/frozenset/list/tuple visited at a depth ``reprlib``
    still enumerates (below ``_PREVIEW_MAX_DEPTH``, which matches its
    ``maxlevel``) holds at least ``_PREVIEW_MAX_ITEMS`` entries — i.e.
    strictly more than ``reprlib``'s per-container limit of one less, the
    condition under which ``reprlib`` drops entries and appends its
    ``...`` fill. ``_log_value_preview`` uses the flag to give over-cap
    reprs whose item truncation is nested (fill not at the end of the
    repr) the explicit ``_PREVIEW_ITEMS_OMITTED_TAIL`` ending.
    Containers at or past the depth cap are handed to ``reprlib``
    untouched and collapse there to ``{...}`` / ``[...]`` wholesale — no
    per-entry output at any item count — so they do not set the flag.
    """
    if _depth >= _PREVIEW_MAX_DEPTH:
        return value, False
    if _key_budget is None:
        _key_budget = [_PREVIEW_KEY_CHECK_BUDGET]
    if isinstance(value, dict):
        bounded: dict[Any, Any] = {}
        omitted = len(value) >= _PREVIEW_MAX_ITEMS
        for k, v in itertools.islice(value.items(), _PREVIEW_MAX_ITEMS):
            # A non-str key is never sensitive and costs nothing to check.
            cost = (
                max(len(k), _PREVIEW_KEY_CHECK_MIN_CHARGE)
                if isinstance(k, str)
                else 0
            )
            if cost > _key_budget[0]:
                # Not checked (see ``_PREVIEW_KEY_CHECK_BUDGET``), so
                # masked unless empty. The walk below only computes the
                # flag: with no budget, everything under it is masked too.
                if not _is_empty_log_value(v):
                    bounded[k] = REDACTION_TEXT
                    _, child_omitted = _bound_dict_shaped_walk(
                        v, _depth + 1, [0]
                    )
                    omitted = omitted or child_omitted
                    continue
            else:
                _key_budget[0] -= cost
                if _is_sensitive_log_key(k) and not _is_empty_log_value(v):
                    # Masked whole, as the log patcher masks a sensitive
                    # ``extra`` key: string redaction cannot see a label
                    # that lives in the key (see ``_RedactingRepr``).
                    bounded[k] = REDACTION_TEXT
                    continue
            bounded[k], child_omitted = _bound_dict_shaped_walk(
                v, _depth + 1, _key_budget
            )
            omitted = omitted or child_omitted
        return bounded, omitted
    if isinstance(value, (set, frozenset)):
        # Bound the count only — set/frozenset elements are NOT recursed
        # into (see the docstring: a frozenset or tuple nested inside a set
        # therefore stays unbounded; unreachable from JSON input, which has
        # no set literal). Rebuilt as a plain ``set``/``frozenset`` rather
        # than ``type(value)(...)``, because a set SUBCLASS with a custom
        # ``__init__`` would come back silently EMPTY or raise ``TypeError``
        # from inside a logging call — turning a 400 into a 500.
        bounded_items = itertools.islice(value, _PREVIEW_MAX_ITEMS)
        if isinstance(value, frozenset):
            return frozenset(bounded_items), len(value) >= _PREVIEW_MAX_ITEMS
        return set(bounded_items), len(value) >= _PREVIEW_MAX_ITEMS
    if isinstance(value, (list, tuple)):
        bounded = []
        omitted = len(value) >= _PREVIEW_MAX_ITEMS
        for v in itertools.islice(value, _PREVIEW_MAX_ITEMS):
            bounded_item, child_omitted = _bound_dict_shaped_walk(
                v, _depth + 1, _key_budget
            )
            bounded.append(bounded_item)
            omitted = omitted or child_omitted
        # Rebuilt as a plain ``tuple``, so a namedtuple degrades to a
        # bare tuple in the preview — acceptable for an audit line.
        bounded_tuple = tuple(bounded) if isinstance(value, tuple) else bounded
        return bounded_tuple, omitted
    return value, False


def _llm_not_configured_response(operation: str) -> JSONResponse:
    """400 for a notes AI route whose LLM is not configured.

    Nine routes in this file run an LLM (``summarize``,
    ``research-questions``, ``suggest-tags``, ``key-concepts``,
    ``fact-check``, ``fact-check/.../grade``, ``synthesize/preview``,
    ``synthesize``, ``versions/semantic-diff``). Every one of them reaches
    ``NoteAIService._get_llm`` -> ``config.llm_config.get_llm``, which raises
    ``LLMNotConfiguredError`` when the user has not chosen a provider/model
    yet -- and on a fresh install that is the FIRST thing these endpoints
    hit. Left to ``handle_api_error`` they answer 500 "contact support"; in
    ``suggest_tags``, whose handler also maps ``ValueError`` to a
    request-validation 400, it came back as a bad-request verdict on a body
    that was perfectly fine. Both send the user looking in the wrong place.

    400 with ``error_type: model_not_configured`` is this repository's
    existing answer for an unconfigured LLM, not a 5xx: see
    ``web/routers/api.py::check_ollama_model`` (the same ``error_type`` for
    an empty ``llm.model``), ``web/routers/followup.py::start_followup``
    (400 before any DB write when ``llm.model`` is empty), and
    ``web/routers/zotero.py::_not_configured_response`` -- "that is a
    client-state problem, not a server error". The 503s in ``rag.py`` and
    ``settings.py`` are NOT the precedent: those are egress-policy
    ``settings_unavailable`` arms, a different condition.

    One helper rather than nine copies so the status, the message and the
    ``error_type`` cannot drift apart route by route. ``operation`` names
    the route in the server-side log only; it never reaches the client, and
    the client message is always the module constant -- never ``str(exc)``,
    whose setup guidance can carry a settings path.
    """
    logger.warning("Notes AI: {} refused, LLM not configured", operation)
    return JSONResponse(
        {
            "success": False,
            "error": LLM_NOT_CONFIGURED_CLIENT_MESSAGE,
            "error_type": "model_not_configured",
        },
        status_code=400,
    )


# Rate limits for AI-heavy endpoints. Split into two buckets so cheap
# FAISS / local-embedding lookups (semantic search, similar notes,
# suggested links, related research) don't drain the same budget as
# expensive LLM calls (summarize, suggest_tags, extract_key_concepts,
# semantic_diff). A user typing through the autocomplete UI shouldn't
# block a single LLM call for a full minute.
#
# ``key_func=_user_key`` keys each bucket per authenticated user; without it
# the global Limiter default (client IP) would let shared-IP users (NAT, lab,
# reverse-proxy-without-trusted-forward-headers) drain each other's
# LLM/synthesis budgets.
_notes_ai_limit = async_shared_limit(
    limiter, "10 per minute", scope="notes_ai", key_func=_user_key
)
_notes_search_limit = limiter.shared_limit(
    "60 per minute", scope="notes_search", key_func=_user_key
)
_notes_synthesize_limit = async_shared_limit(
    limiter, "5 per minute", scope="notes_synthesize", key_func=_user_key
)
# Notes write budget — applies to create_note, update_note, delete_note,
# and add/remove from collection. 60/min comfortably covers active
# editing (a save every second for a minute) but blocks scripted abuse:
# pre-fix an authenticated user could rapid-POST PUT /api/notes/<id>
# under the global IP cap (5000/hr) and saturate the 4-worker
# summary_executor with bursty LLM change-summary tasks, queueing
# hundreds of MB of (old, new) content pairs. Per-user keying so two
# real users on shared NAT don't compete for the same bucket.
_notes_write_limit = limiter.shared_limit(
    "60 per minute", scope="notes_write", key_func=_user_key
)
# Save-as-note copies a whole completed report (up to the 50MB content
# cap) into a fresh note + version snapshot per call. At the generic
# notes_write 60/min that's on the order of GBs/min of per-user DB writes
# from one client — a disk/backup-bloat vector. Tighter, cost-aware bucket.
_notes_save_as_note_limit = limiter.shared_limit(
    "10 per minute", scope="notes_save_as_note", key_func=_user_key
)
# Fact-check kicks off a full LDR research run downstream, so it's strictly
# tighter than the LLM bucket — a few per minute bounds research load.
_notes_factcheck_limit = async_shared_limit(
    limiter, "3 per minute", scope="notes_factcheck", key_func=_user_key
)

router = APIRouter(prefix="/notes", tags=["notes"])

# Pre-parse request-body ceiling for this JSON API surface. The app-wide
# request size limit is sized for multi-file uploads (hundreds of GB), and
# parsing buffers the WHOLE body before any service validation runs — so
# without this check a multi-GB JSON body reached memory before
# _assert_content_size could reject it at 50 MB.
#
# Budget 2× the content cap. This bounds pre-parse memory; it does NOT
# precisely enforce the 50 MB content limit (that stays in
# _assert_content_size after parsing). 2× covers the realistic worst case
# where every character needs a 2-byte JSON escape (``"`` / ``\`` /
# newline); content dominated by control chars (each expands to a 6-byte
# ``\uXXXX``) can still exceed this and get a 413 even though its decoded
# size is under 50 MB — an acceptable trade for keeping the cap far below
# a memory-exhausting multi-GB body.
_MAX_JSON_BODY_BYTES = 2 * NOTE_CONTENT_MAX_BYTES


#: Above this size the JSON parse is handed to a worker thread. Measured on
#: the pinned interpreter with an adversarial-but-valid document (many small
#: objects, which is what an attacker sends -- not one long string, which is
#: what a benign client sends), ``json.loads`` runs at ~110 ms/MB and scales
#: linearly. So 64 KiB is ~7 ms on the loop, and the notes ceiling of 100 MB
#: would be ~11 SECONDS -- a whole-instance freeze under single-worker
#: uvicorn, where Flask's thread-per-request model only cost one thread.
#: Below the threshold the parse is sub-10 ms and dispatching it would trade
#: that for contention on the same threadpool the DB work uses.
_JSON_OFFLOAD_THRESHOLD_BYTES = 64 * 1024


async def _parse_json_off_loop(body):
    """``json.loads`` without stalling the event loop on a large body.

    ``asyncio.to_thread`` rather than ``run_db_sync``: this opens no DB
    session, so the session cleanup that wrapper does is unnecessary
    (see dependencies/threadpool.py::run_db_sync).

    The bytearray is passed through without copying to ``bytes`` -- at the
    notes cap that copy would itself be a 100 MB allocation, and nothing
    mutates the buffer after this point.
    """
    if len(body) < _JSON_OFFLOAD_THRESHOLD_BYTES:
        return json.loads(body)
    return await asyncio.to_thread(json.loads, body)


async def _notes_json_body(
    request: Request,
) -> dict[str, Any] | JSONResponse:
    """Shared body gate for every mutating notes route.

    Replaces the blueprint's two ``before_request`` hooks:

      * 413 a body whose ``Content-Length`` exceeds ``_MAX_JSON_BODY_BYTES``
        (bounds pre-parse memory before ``request.json()`` buffers it).
      * 400 a declared-JSON body that parses to something other than an
        object — ``true`` / ``123`` / ``"x"`` / ``[1, 2]`` would otherwise
        slip past the routes' ``... or {}`` idioms and crash on the first
        ``.get`` as an opaque 500.

    Returns either a ``JSONResponse`` (the caller must return it verbatim) or
    the parsed dict. A missing/empty/malformed body becomes ``{}`` so each
    route applies its own "no data provided" default exactly as before.
    """

    def _too_large():
        return JSONResponse(
            {
                "success": False,
                "error": (
                    "Request body too large "
                    f"(max {_MAX_JSON_BODY_BYTES // (1024 * 1024)} MB)"
                ),
            },
            status_code=413,
        )

    # Fast path: reject a body that DECLARES an over-cap Content-Length before
    # reading anything.
    content_length = request.headers.get("content-length")
    if content_length is not None:
        try:
            declared = int(content_length)
        except (TypeError, ValueError):
            declared = None
        if declared is not None and declared > _MAX_JSON_BODY_BYTES:
            return _too_large()

    # Read the body from the stream with a running cap, so a chunked request
    # (``Transfer-Encoding: chunked``, no Content-Length) is cut off at the
    # notes ceiling BEFORE it is fully buffered — the Flask blueprint got this
    # from ``arm_notes_body_cap`` setting ``request.max_content_length`` at the
    # stream level; the plain Content-Length check above cannot (a chunked
    # body has no Content-Length to inspect). No notes route reads the body
    # again after this dependency, so consuming the stream here is safe.
    body = bytearray()
    async for chunk in request.stream():
        body.extend(chunk)
        if len(body) > _MAX_JSON_BODY_BYTES:
            return _too_large()

    # Keep the body cap for every media type. Flask's get_json(silent=True)
    # then treated a non-JSON media type as no data, even when its bytes
    # looked like JSON.
    if not is_json_request(request):
        return {}

    if not body:
        # Missing/empty body — leave the route to default as it sees fit
        # (matches Flask's ``get_json(silent=True) -> None``).
        return {}
    try:
        data = await _parse_json_off_loop(body)
    except Exception:
        # Malformed JSON — same "leave the route to default" behavior.
        return {}

    if not isinstance(data, dict):
        return JSONResponse(
            {
                "success": False,
                "error": "Request body must be a JSON object",
            },
            status_code=400,
        )
    return data


_NotesBody = Annotated[
    dict[str, Any] | JSONResponse,
    Depends(_notes_json_body),
]


def _trigger_note_auto_index(note_id, service, username, session_id):
    """Trigger async auto-indexing for a note (non-blocking)."""
    try:
        from ...web.routers.rag import trigger_auto_index
        from ...database.session_passwords import session_password_store

        db_password = session_password_store.get_session_password(
            username, session_id
        )
        if not db_password:
            logger.debug(
                "Skipping note auto-index for {}: no session password available",
                note_id,
            )
            return
        collection_id = service.get_notes_collection_id()
        if not collection_id:
            logger.debug(
                "Skipping note auto-index for {}: no notes collection",
                note_id,
            )
            return
        trigger_auto_index([note_id], collection_id, username, db_password)
    except Exception:
        logger.exception("Failed to trigger auto-indexing for note")


# ============================================================================
# Page Routes
# ============================================================================


@router.get("/")
def notes_page(
    request: Request, username: Annotated[str, Depends(require_auth)]
):
    """Render the notes list page."""
    return templates.TemplateResponse(
        request=request,
        name="pages/notes.html",
        context={"active_page": "notes"},
    )


@router.get("/{note_id}")
def note_detail_page(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Render the note detail page."""
    from ..utils.path_ids import validated_uuid_path_param

    note_id = validated_uuid_path_param(note_id, "Note")
    return templates.TemplateResponse(
        request=request,
        name="pages/note_detail.html",
        context={"active_page": "notes", "note_id": note_id},
    )


# ============================================================================
# API Routes - Notes CRUD
# ============================================================================


@router.get("/api/notes")
@_notes_search_limit
def list_notes(
    request: Request, username: Annotated[str, Depends(require_auth)]
):
    """
    List notes with optional filtering.

    Query params:
        collection_id: Filter by collection
        search: Search in title and content (capped at MAX_SEARCH_LEN)
        pinned_only: Only return pinned notes
        limit: Maximum number (default 100)
        offset: Offset for pagination (default 0)
    """
    try:
        service = NoteService(username)

        collection_id = request.query_params.get("collection_id")
        try:
            search = _clamp_text_query(
                request.query_params.get("search"), "search"
            )
        except ValueError:
            return JSONResponse(
                {
                    "success": False,
                    "error": (
                        f"search exceeds maximum length "
                        f"({MAX_SEARCH_LEN} chars)"
                    ),
                },
                status_code=400,
            )
        pinned_only = (
            request.query_params.get("pinned_only", "").lower() == "true"
        )
        try:
            limit = _clamp_limit(request, 100)
            offset = max(0, int(request.query_params.get("offset", 0)))
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit or offset"},
                status_code=400,
            )

        # Total under the same filter — lets the frontend render a real
        # page-N-of-M control rather than guessing from len(notes) ==
        # limit. count_notes repeats the filtered scan list_notes runs
        # (for a keyword search that is a second full ILIKE pass over
        # text_content), so skip it when a short first page already
        # reveals the total.
        if offset == 0:
            notes = service.list_notes(
                collection_id=collection_id,
                search=search,
                pinned_only=pinned_only,
                limit=limit,
                offset=0,
            )
            total = (
                len(notes)
                if len(notes) < limit
                else service.count_notes(
                    collection_id=collection_id,
                    search=search,
                    pinned_only=pinned_only,
                )
            )
        else:
            total = service.count_notes(
                collection_id=collection_id,
                search=search,
                pinned_only=pinned_only,
            )
            # Clamp an offset past the end of the result set: it returns
            # an empty page anyway, so don't make the DB scan-and-discard
            # `offset` rows for a guaranteed-empty result (mirrors
            # get_note_versions).
            if offset > total:
                offset = total

            notes = service.list_notes(
                collection_id=collection_id,
                search=search,
                pinned_only=pinned_only,
                limit=limit,
                offset=offset,
            )

        return {
            "success": True,
            "notes": notes,
            "total": total,
            "limit": limit,
            "offset": offset,
        }

    except Exception as e:
        return handle_api_error("listing notes", e)


@router.post("/api/notes")
@_notes_write_limit
def create_note(
    request: Request,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Create a new note.

    Body:
        title: Note title (required)
        content: Note content (required)
        tags: List of tags (optional)
        collection_ids: List of collection IDs (optional)
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not isinstance(data, dict) or not data:
            # get_json returns the parsed body verbatim, so a top-level JSON
            # array/string/number would pass a bare truthiness check and then
            # crash data.get() with AttributeError → opaque 500. Require an
            # object.
            return JSONResponse(
                {"success": False, "error": "No data provided"},
                status_code=400,
            )

        title = data.get("title")
        content = data.get("content")

        if not title:
            return JSONResponse(
                {"success": False, "error": "Title is required"},
                status_code=400,
            )
        if not content:
            return JSONResponse(
                {"success": False, "error": "Content is required"},
                status_code=400,
            )

        service = NoteService(username)
        note_id = service.create_note(
            title=title,
            content=content,
            tags=data.get("tags"),
            collection_ids=data.get("collection_ids"),
        )

        # Trigger async auto-indexing (non-blocking)
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )

        return JSONResponse({"success": True, "id": note_id}, status_code=201)

    except ValueError:
        # Never serialize exception text at the HTTP boundary. Even callers
        # that normally raise fixed validation messages can regress to an
        # exception containing paths, SQL, credentials, or library internals.
        return JSONResponse(
            {"success": False, "error": "Invalid note data"}, status_code=400
        )
    except Exception as e:
        return handle_api_error("creating note", e)


# ---------------------------------------------------------------------------
# Literal-path GET routes under /api/notes/... MUST be registered before
# GET /api/notes/{note_id} below — Starlette matches routes in registration
# order, so otherwise ``/api/notes/semantic-search`` etc. would be captured
# by the ``{note_id}`` route. (Flask's URL map gave static rules priority
# automatically; FastAPI does not.)
# ---------------------------------------------------------------------------


@router.get("/api/notes/semantic-search")
@_notes_search_limit
def semantic_search_notes(
    request: Request, username: Annotated[str, Depends(require_auth)]
):
    """
    Search notes using semantic similarity.

    Finds notes by meaning rather than keyword matching.

    Query params:
        q: Search query (required)
        limit: Maximum results (default 10)
        min_similarity: Minimum similarity threshold 0.0-1.0 (default 0.3)
        collection_id: Optional — restrict results to this collection's notes
            (matches the text-search filter).
    """
    try:
        try:
            query = _clamp_text_query(request.query_params.get("q", ""), "q")
        except ValueError:
            return JSONResponse(
                {
                    "success": False,
                    "error": f"q exceeds maximum length ({MAX_SEARCH_LEN} chars)",
                },
                status_code=400,
            )
        query = (query or "").strip()
        if not query:
            return JSONResponse(
                {"success": False, "error": "Query is required"},
                status_code=400,
            )

        try:
            limit = _clamp_limit(request, 10)
            min_similarity_raw = float(
                request.query_params.get("min_similarity", 0.3)
            )
            min_similarity = max(0.0, min(min_similarity_raw, 1.0))
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit or min_similarity"},
                status_code=400,
            )
        if not math.isfinite(min_similarity_raw):
            logger.warning(
                "notes_api validation reject: min_similarity={!r} (non-finite) "
                "(user={!r})",
                min_similarity_raw,
                username,
            )
            return JSONResponse(
                {"success": False, "error": "Invalid limit or min_similarity"},
                status_code=400,
            )

        collection_id = request.query_params.get("collection_id") or None

        service = NoteAIService(username)
        results = service.semantic_search(
            query,
            limit=limit,
            min_similarity=min_similarity,
            collection_id=collection_id,
        )

        return {
            "success": True,
            "query": query,
            "results": results,
            "count": len(results),
        }

    except Exception as e:
        return handle_api_error("semantic search", e)


@router.get("/api/notes/ask-context")
@_notes_search_limit
def ask_context(
    request: Request, username: Annotated[str, Depends(require_auth)]
):
    """Pre-flight context for the 'Ask your notes' box: the Notes collection
    id + note/indexed counts, so the UI can warn when there's nothing to
    search before starting a research run pinned to that collection.
    """
    try:
        service = NoteService(username)
        status = service.get_notes_index_status()
        return {"success": True, **status}
    except Exception as e:
        return handle_api_error("getting ask-notes context", e)


@router.get("/api/notes/search-for-linking")
@_notes_search_limit
def search_notes_for_linking(
    request: Request, username: Annotated[str, Depends(require_auth)]
):
    """
    Search notes for the [[link]] autocomplete feature.

    Query params:
        query: Search query (partial title match)
        exclude_note_id: Note ID to exclude from results
        limit: Maximum number of results (default 10)
    """
    try:
        try:
            query = _clamp_text_query(
                request.query_params.get("query", ""), "query"
            )
        except ValueError:
            return JSONResponse(
                {
                    "success": False,
                    "error": (
                        f"query exceeds maximum length ({MAX_SEARCH_LEN} chars)"
                    ),
                },
                status_code=400,
            )
        if not query:
            return {"success": True, "notes": []}

        exclude_note_id = request.query_params.get("exclude_note_id")
        try:
            limit = _clamp_limit(request, 10)
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit"}, status_code=400
            )

        service = NoteService(username)
        notes = service.search_notes_for_linking(query, exclude_note_id, limit)

        return {"success": True, "notes": notes}

    except Exception as e:
        return handle_api_error("searching notes for linking", e)


@router.get("/api/notes/{note_id}")
def get_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get a specific note."""
    try:
        service = NoteService(username)
        note = service.get_note(note_id)

        if not note:
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        return {"success": True, "note": note}

    except Exception as e:
        return handle_api_error("getting note", e)


@router.put("/api/notes/{note_id}")
@_notes_write_limit
def update_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Update a note.

    Body:
        title: New title (optional)
        content: New content (optional)
        tags: New tags (optional)
        pinned: New pinned status (optional) — wire-level alias for the
            ``Document.favorite`` column; the UI vocabulary is "pin".
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data:
            return JSONResponse(
                {"success": False, "error": "No data provided"},
                status_code=400,
            )

        # Every sibling field gets a clean 400 via the service validators
        # (_validate_title/_assert_content_size/_validate_tags); pinned is
        # assigned straight into the Boolean column, where a non-bool
        # raises StatementError at flush → an opaque 500.
        pinned = data.get("pinned")
        if pinned is not None and not isinstance(pinned, bool):
            return JSONResponse(
                {"success": False, "error": "pinned must be a boolean"},
                status_code=400,
            )

        service = NoteService(username)
        content_provided = data.get("content") is not None
        try:
            success = service.update_note(
                note_id=note_id,
                title=data.get("title"),
                content=data.get("content"),
                tags=data.get("tags"),
                favorite=pinned,
            )
        except ValueError:
            return JSONResponse(
                {"success": False, "error": "Invalid note data"},
                status_code=400,
            )

        if not success:
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        # Trigger async auto-indexing if content OR title was updated
        # (non-blocking). The service marks DocumentCollection.indexed=False
        # for either change and relies on this post-commit trigger; the
        # title is baked into every chunk's metadata at index time, so a
        # rename leaves stale titles in search results until reindexed. A
        # title-only PUT used to flip indexed=False without ever scheduling
        # the reindex. Unchanged values are harmless: the worker runs with
        # force_reindex=False and skips rows still marked indexed=True.
        if content_provided or data.get("title") is not None:
            _trigger_note_auto_index(
                note_id, service, username, request.session.get("session_id")
            )

        return {"success": True}

    except Exception as e:
        return handle_api_error("updating note", e)


@router.delete("/api/notes/{note_id}")
@_notes_write_limit
def delete_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Delete a note."""
    try:
        service = NoteService(username)
        success = service.delete_note(note_id)

        if not success:
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        return {"success": True}

    except Exception as e:
        return handle_api_error("deleting note", e)


# ============================================================================
# API Routes - Collections
# ============================================================================


@router.get("/api/notes/{note_id}/collections")
def get_note_collections(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get collections a note belongs to."""
    try:
        service = NoteService(username)
        # 404 on unknown note id rather than returning an empty list.
        # Pre-fix, a typo in the note UUID returned 200 with [] —
        # indistinguishable from "this note has no collections" — making
        # client-side bugs invisible to QA. The sibling get_note route
        # already 404s for unknown ids; align with that contract.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        collections = service.get_note_collections(note_id)

        return {"success": True, "collections": collections}

    except Exception as e:
        return handle_api_error("getting note collections", e)


@router.post("/api/notes/{note_id}/collections")
@_notes_write_limit
def add_note_to_collection(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Add a note to a collection.

    Body:
        collection_id: The collection ID
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("collection_id"):
            return JSONResponse(
                {"success": False, "error": "collection_id is required"},
                status_code=400,
            )

        service = NoteService(username)
        # add_to_collection returns the same False for "note id missing /
        # not a note" and "already a member"; without this guard a stale
        # id (note deleted in another tab) produced a factually wrong 409
        # "Already in collection". 404 first, like get_note_collections.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        success = service.add_to_collection(note_id, data["collection_id"])

        if not success:
            return JSONResponse(
                {"success": False, "error": "Already in collection"},
                status_code=409,
            )

        return {"success": True}

    except LookupError:
        return JSONResponse(
            {"success": False, "error": "Collection not found"},
            status_code=404,
        )
    except Exception as e:
        return handle_api_error("adding note to collection", e)


@router.delete("/api/notes/{note_id}/collections/{collection_id}")
@_notes_write_limit
def remove_note_from_collection(
    request: Request,
    note_id: str,
    collection_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Remove a note from a collection."""
    try:
        service = NoteService(username)
        # Same conflation as add_note_to_collection: a missing/non-note id
        # used to 404 with the misleading "Not in collection" message.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        success = service.remove_from_collection(note_id, collection_id)

        if not success:
            return JSONResponse(
                {"success": False, "error": "Not in collection"},
                status_code=404,
            )

        return {"success": True}

    except ValueError:
        return JSONResponse(
            {
                "success": False,
                "error": "Note cannot be removed from this collection",
            },
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("removing note from collection", e)


# ============================================================================
# API Routes - Research
# ============================================================================


@router.get("/api/notes/{note_id}/research")
def get_note_research(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get research runs triggered from a note."""
    try:
        service = NoteService(username)
        # 404 on unknown note id — see get_note_collections for the
        # rationale. The two routes had the same contract gap.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        research = service.get_note_research(note_id)

        return {"success": True, "research": research}

    except Exception as e:
        return handle_api_error("getting note research", e)


@router.post("/api/notes/{note_id}/research")
@_notes_write_limit
def link_research_to_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Link a research run to a note.

    Body:
        research_id: The research history ID
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("research_id"):
            return JSONResponse(
                {"success": False, "error": "research_id is required"},
                status_code=400,
            )

        service = NoteService(username)
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        link_id = service.link_research_to_note(
            note_id=note_id,
            research_id=data["research_id"],
        )

        return JSONResponse({"success": True, "id": link_id}, status_code=201)

    except ValueError:
        # The pre-check above answers 404 for an id that was already unknown.
        # A note DELETED between that check and the service call lands here
        # instead (the service raises ValueError("... not found")), so re-run
        # the existence check to keep that narrow race answering 404 rather
        # than a misleading "cannot be linked" 400. Best-effort: this runs
        # inside an except handler, so a failure of the re-check itself must
        # not replace the 400 with a 500.
        try:
            if not NoteService(username).note_exists(note_id):
                return JSONResponse(
                    {"success": False, "error": "Note not found"},
                    status_code=404,
                )
        except Exception:
            logger.warning(
                "notes_api: note_exists re-check failed while classifying a "
                "link-research failure (user={!r})",
                username,
            )
        return JSONResponse(
            {
                "success": False,
                "error": "Research cannot be linked to this note",
            },
            status_code=400,
        )
    except IntegrityError as exc:
        # Only the (document_id, research_id) uniqueness collision means the
        # research is already linked → 409. A display_order retry-exhaustion
        # or an FK race (stale/deleted research_id) also surfaces as
        # IntegrityError but is NOT a duplicate — don't mislabel those as
        # "already linked"; let them fall through to a generic error.
        msg = str(getattr(exc, "orig", exc)).lower()
        if "foreign key" in msg:
            # research_id references a research run that doesn't exist (or
            # was deleted) — a client-fixable 404, not an opaque 500.
            return JSONResponse(
                {"success": False, "error": "Research run not found"},
                status_code=404,
            )
        if "display_order" in msg:
            return handle_api_error("linking research to note", exc)
        return JSONResponse(
            {"success": False, "error": "Research already linked to this note"},
            status_code=409,
        )
    except Exception as e:
        return handle_api_error("linking research to note", e)


@router.patch("/api/notes/{note_id}/research/{research_id}")
@_notes_write_limit
def patch_note_research(
    request: Request,
    note_id: str,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Update a NoteResearch row (currently supports is_collapsed toggle).

    Body:
        is_collapsed: bool (optional)
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        # Omitted: is_collapsed stays None and is passed through (no-op).
        is_collapsed = data.get("is_collapsed")
        if "is_collapsed" in data and not isinstance(
            data["is_collapsed"], bool
        ):
            logger.warning(
                "notes_api validation reject: is_collapsed={} (type={}) "
                "(user={!r})",
                _log_value_preview(data["is_collapsed"]),
                type(data["is_collapsed"]).__name__,
                username,
            )
            return JSONResponse(
                {
                    "success": False,
                    "error": "is_collapsed must be a boolean",
                },
                status_code=400,
            )
        service = NoteService(username)
        updated = service.update_note_research(
            note_id=note_id,
            research_id=research_id,
            is_collapsed=is_collapsed,
        )
        if not updated:
            return JSONResponse(
                {"success": False, "error": "Research link not found"},
                status_code=404,
            )
        return {"success": True}

    except Exception as e:
        return handle_api_error("updating note research", e)


@router.post("/api/notes/{note_id}/research/reorder")
@_notes_write_limit
def reorder_note_research(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Atomically reorder research items for a note.

    Body:
        research_ids: list of research_id strings in desired display order.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        research_ids = data.get("research_ids")
        if not isinstance(research_ids, list) or not research_ids:
            return JSONResponse(
                {
                    "success": False,
                    "error": "research_ids must be a non-empty list",
                },
                status_code=400,
            )
        if not all(isinstance(r, str) for r in research_ids):
            # Non-string elements (nested arrays/objects) are unhashable and
            # crash the dedup/reorder logic with TypeError → opaque 500.
            return JSONResponse(
                {
                    "success": False,
                    "error": "research_ids must be a list of strings",
                },
                status_code=400,
            )

        service = NoteService(username)
        # 404 a stale/deleted note id BEFORE the ids-match check, mirroring
        # every sibling note-scoped route (get_note_research,
        # add_note_to_collection, ...). Otherwise reorder_note_research finds
        # no NoteResearch rows for the missing note, returns False on the
        # ids-mismatch path, and the route misreports a 404 condition (note
        # deleted in another tab) as a 400 validation error.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        ok = service.reorder_note_research(note_id, research_ids)
        if not ok:
            return JSONResponse(
                {
                    "success": False,
                    "error": "research_ids do not match the note's linked research",
                },
                status_code=400,
            )
        return {"success": True}

    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid research order"},
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("reordering note research", e)


# ============================================================================
# API Routes - Research → Notes (results-page Notes panel)
# ============================================================================


@router.get("/api/research/{research_id}/notes")
@_notes_search_limit
def get_research_notes(
    request: Request,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """List the notes linked to a research run.

    The reverse of GET /api/notes/<id>/research — powers the Notes panel
    on the research results page, so commentary attached to a run is
    visible from the run itself, not only from the note.
    """
    try:
        service = NoteService(username)
        notes = service.get_notes_for_research(research_id)
        if notes is None:
            return JSONResponse(
                {"success": False, "error": "Research not found"},
                status_code=404,
            )
        return {"success": True, "notes": notes}

    except Exception as e:
        return handle_api_error("listing notes for research", e)


@router.post("/api/research/{research_id}/notes")
@_notes_write_limit
def create_research_note(
    request: Request,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Create a note pre-linked to a research run (all-or-nothing).

    Body (all optional): ``title``, ``content``, ``tags``. Defaults
    produce a starter note titled after the research query. The results
    page's "Add note" (no body) and "Clip to note" (content = the quoted
    selection) both come through here.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        service = NoteService(username)
        try:
            note_id = service.create_note_for_research(
                research_id,
                title=data.get("title"),
                content=data.get("content"),
                tags=data.get("tags"),
            )
        except LookupError:
            return JSONResponse(
                {"success": False, "error": "Research not found"},
                status_code=404,
            )
        # Reach semantic search / "Ask your notes" like a normally-created
        # note (the plain POST /api/notes route does the same at its tail).
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )
        return JSONResponse(
            {"success": True, "note_id": note_id}, status_code=201
        )

    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid note data"}, status_code=400
        )
    except Exception as e:
        return handle_api_error("creating note for research", e)


@router.post("/api/research/{research_id}/save-as-note")
@_notes_save_as_note_limit
def save_research_as_note(
    request: Request,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Copy a COMPLETED research run's report into a new, linked note.

    Deliberately a derivation, not a conversion: the report stays the
    immutable record (fact-check grades claims against it and its
    provenance must survive), while the note is the user's editable
    copy. Provenance is kept twice — the NoteResearch link and a header
    line inside the note content — so the copy stays traceable even if
    it is later unlinked.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        from ...constants import ResearchStatus
        from ...database.models import ResearchHistory
        from ...database.session_context import get_user_db_session
        from ...storage import get_report_storage

        with get_user_db_session(username) as db:
            research = (
                db.query(ResearchHistory).filter_by(id=research_id).first()
            )
            if research is None:
                return JSONResponse(
                    {"success": False, "error": "Research not found"},
                    status_code=404,
                )
            if research.status != ResearchStatus.COMPLETED:
                return JSONResponse(
                    {
                        "success": False,
                        "error": "Research is not complete yet.",
                        "status": research.status,
                    },
                    status_code=409,
                )
            query_text = (research.query or "").strip()
            meta = dict(research.research_meta or {})

        # Fetch the report markdown in-request (same pattern as the
        # fact-check grade flow: the per-user DB password is available
        # here, unlike in a background worker).
        settings_snapshot = meta.get("settings_snapshot")
        with get_user_db_session(username) as db:
            storage = get_report_storage(
                session=db, settings_snapshot=settings_snapshot
            )
            report = storage.get_report(research_id, username)

        if not report or not str(report).strip():
            # get_report returns None for BOTH a missing report and a
            # swallowed read error; saving an empty note would look like
            # success while losing the content. Refuse instead.
            return JSONResponse(
                {
                    "success": False,
                    "error": (
                        "The research report is unavailable, so it cannot "
                        "be saved as a note. Try re-running the research."
                    ),
                },
                status_code=502,
            )

        from ...research_library.notes.services.note_service import (
            MAX_TITLE_LENGTH,
        )

        title = (
            f"Research: {query_text}"[:MAX_TITLE_LENGTH]
            if query_text
            else f"Research {research_id[:8]}"
        )
        provenance = (
            f"> Saved from the research run "
            f"[{escape_markdown_link_label(query_text or research_id)}]"
            f"(/results/{research_id}).\n\n"
        )

        service = NoteService(username)
        try:
            note_id = service.create_note_for_research(
                research_id, title=title, content=provenance + str(report)
            )
        except LookupError:
            # Deleted between the checks above and the create — treat like
            # any other missing research.
            return JSONResponse(
                {"success": False, "error": "Research not found"},
                status_code=404,
            )
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )
        return JSONResponse(
            {"success": True, "note_id": note_id}, status_code=201
        )

    except ValueError:
        return JSONResponse(
            {
                "success": False,
                "error": "Research cannot be saved as a note",
            },
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("saving research as note", e)


# ============================================================================
# API Routes - Inline annotations (Word-review-style comments) and
# document-linked notes. Targets: research runs and library documents —
# both have IMMUTABLE rendered text, so quote anchors can never drift.
# The comment itself is a full NOTE; the anchor lives in note_references.
# ============================================================================

MAX_ANNOTATION_COMMENT_LEN = 5000
MAX_ANNOTATION_QUOTE_LEN = 1000
MAX_ANNOTATION_CONTEXT_LEN = 100


def _validated_annotation_fields(data):
    """Validate/trim an annotation payload; raises ValueError.

    Type-checks every field before touching it: a non-string comment
    (e.g. ``{"comment": 123}`` from a direct API caller) would otherwise
    crash on ``.strip()`` as an opaque 500 instead of the clean 400 the
    length checks produce.
    """
    for field in ("comment", "quote", "prefix", "suffix"):
        value = data.get(field)
        if value is not None and not isinstance(value, str):
            raise ValueError(f"{field} must be a string")
    comment = (data.get("comment") or "").strip()
    quote = (data.get("quote") or "").strip()
    if not comment:
        raise ValueError("comment is required")
    if not quote:
        raise ValueError("quote is required")
    if len(comment) > MAX_ANNOTATION_COMMENT_LEN:
        raise ValueError(
            f"comment exceeds maximum length "
            f"({MAX_ANNOTATION_COMMENT_LEN} chars)"
        )
    if len(quote) > MAX_ANNOTATION_QUOTE_LEN:
        raise ValueError(
            f"quote exceeds maximum length ({MAX_ANNOTATION_QUOTE_LEN} chars)"
        )
    prefix = (data.get("prefix") or "")[-MAX_ANNOTATION_CONTEXT_LEN:]
    suffix = (data.get("suffix") or "")[:MAX_ANNOTATION_CONTEXT_LEN]
    return comment, quote, prefix, suffix


def _comment_note_title(comment):
    """Derive the comment-note's title from its first words."""
    one_line = " ".join(comment.split())
    if len(one_line) > 60:
        one_line = one_line[:60].rstrip() + "…"
    return f"Comment: {one_line}"


# Length of the comment preview echoed back in an annotation response (was
# a bare 300 duplicated across both create-annotation handlers).
_ANNOTATION_COMMENT_PREVIEW_CHARS = 300


def _annotation_response(note_id, comment, quote, prefix, suffix):
    """The annotation-created response payload shared by the research and
    document create-annotation handlers (previously byte-identical dicts)."""
    return {
        "note_id": note_id,
        "quote": quote,
        "prefix": prefix,
        "suffix": suffix,
        "note_title": _comment_note_title(comment),
        "comment_preview": comment[:_ANNOTATION_COMMENT_PREVIEW_CHARS],
    }


def _comment_note_content(comment, quote, target_label, target_url):
    """Comment-first note body: remark, quoted passage, provenance.

    ``target_label`` (a research query or a library document title, both
    potentially untrusted) is escaped so it can't break out of the
    provenance link — see ``escape_markdown_link_label``.
    """
    quote_block = "\n".join(f"> {line}" for line in quote.split("\n"))
    label = escape_markdown_link_label(target_label)
    return (
        f"{comment}\n\n{quote_block}\n\n— comment on [{label}]({target_url})\n"
    )


def _research_exists(username, research_id):
    """(exists, query_text) for a research id in the user's DB."""
    from ...database.models import ResearchHistory
    from ...database.session_context import get_user_db_session

    with get_user_db_session(username) as db:
        row = (
            db.query(ResearchHistory.id, ResearchHistory.query)
            .filter_by(id=research_id)
            .first()
        )
    if row is None:
        return False, None
    return True, (row.query or "").strip()


@router.get("/api/research/{research_id}/annotations")
@_notes_search_limit
def get_research_annotations(
    request: Request,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """List a research run's inline annotations (anchored comment notes)."""
    try:
        exists, _query = _research_exists(username, research_id)
        if not exists:
            return JSONResponse(
                {"success": False, "error": "Research not found"},
                status_code=404,
            )
        service = NoteService(username)
        annotations = service.get_annotations_for_target(
            research_id=research_id
        )
        return {"success": True, "annotations": annotations}

    except Exception as e:
        return handle_api_error("listing research annotations", e)


@router.post("/api/research/{research_id}/annotations")
@_notes_write_limit
def create_research_annotation(
    request: Request,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Attach a comment to a passage of the research report.

    Body: ``quote`` (the selected rendered text), optional ``prefix`` /
    ``suffix`` (Hypothesis-style disambiguation context), ``comment``.
    The comment becomes a NOTE linked to the run; the anchor is a
    note_references row.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        comment, quote, prefix, suffix = _validated_annotation_fields(data)

        exists, query_text = _research_exists(username, research_id)
        if not exists:
            return JSONResponse(
                {"success": False, "error": "Research not found"},
                status_code=404,
            )

        service = NoteService(username)
        note_id = service.create_note_for_research(
            research_id,
            title=_comment_note_title(comment),
            content=_comment_note_content(
                comment,
                quote,
                query_text or research_id,
                f"/results/{research_id}",
            ),
            quote=quote,
            prefix=prefix,
            suffix=suffix,
        )
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )
        return JSONResponse(
            {
                "success": True,
                "annotation": _annotation_response(
                    note_id, comment, quote, prefix, suffix
                ),
            },
            status_code=201,
        )

    except LookupError:
        return JSONResponse(
            {"success": False, "error": "Research not found"}, status_code=404
        )
    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid annotation data"},
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("creating research annotation", e)


@router.delete("/api/research/{research_id}/annotations/{note_id}")
@_notes_write_limit
def delete_research_annotation(
    request: Request,
    research_id: str,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Remove an annotation: the comment note is deleted (standard delete
    path — version cascade, vector purge) and its anchor row cascades."""
    try:
        service = NoteService(username)
        if not service.has_annotation(note_id, research_id=research_id):
            return JSONResponse(
                {"success": False, "error": "Annotation not found"},
                status_code=404,
            )
        service.delete_note(note_id)
        return {"success": True}

    except Exception as e:
        return handle_api_error("deleting research annotation", e)


# ---- Library documents: same surface, document targets --------------------


@router.get("/api/documents/{document_id}/notes")
@_notes_search_limit
def get_document_notes(
    request: Request,
    document_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """List the notes referencing a library document (its Notes panel)."""
    try:
        service = NoteService(username)
        notes = service.get_notes_for_document(document_id)
        if notes is None:
            return JSONResponse(
                {"success": False, "error": "Document not found"},
                status_code=404,
            )
        return {"success": True, "notes": notes}

    except Exception as e:
        return handle_api_error("listing notes for document", e)


@router.post("/api/documents/{document_id}/notes")
@_notes_write_limit
def create_document_note(
    request: Request,
    document_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Create a note referencing a library document (all-or-nothing).

    Body (all optional): ``title``, ``content``, ``tags``. Defaults
    produce a starter note titled after the document.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        service = NoteService(username)
        try:
            note_id = service.create_note_for_document(
                document_id,
                title=data.get("title"),
                content=data.get("content"),
                tags=data.get("tags"),
            )
        except LookupError:
            return JSONResponse(
                {"success": False, "error": "Document not found"},
                status_code=404,
            )
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )
        return JSONResponse(
            {"success": True, "note_id": note_id}, status_code=201
        )

    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid document note data"},
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("creating note for document", e)


@router.get("/api/documents/{document_id}/annotations")
@_notes_search_limit
def get_document_annotations(
    request: Request,
    document_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """List a library document's inline annotations."""
    try:
        service = NoteService(username)
        # Existence gate doubles as the 404 (get_notes_for_document
        # checks the Document row).
        if service.get_notes_for_document(document_id) is None:
            return JSONResponse(
                {"success": False, "error": "Document not found"},
                status_code=404,
            )
        annotations = service.get_annotations_for_target(
            document_id=document_id
        )
        return {"success": True, "annotations": annotations}

    except Exception as e:
        return handle_api_error("listing document annotations", e)


@router.post("/api/documents/{document_id}/annotations")
@_notes_write_limit
def create_document_annotation(
    request: Request,
    document_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Attach a comment to a passage of a library document's text."""
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        comment, quote, prefix, suffix = _validated_annotation_fields(data)

        from ...database.models import Document
        from ...database.session_context import get_user_db_session

        with get_user_db_session(username) as db:
            row = (
                db.query(Document.id, Document.title)
                .filter_by(id=document_id)
                .first()
            )
        if row is None:
            return JSONResponse(
                {"success": False, "error": "Document not found"},
                status_code=404,
            )
        doc_title = (row.title or "").strip() or document_id

        service = NoteService(username)
        note_id = service.create_note_for_document(
            document_id,
            title=_comment_note_title(comment),
            content=_comment_note_content(
                comment,
                quote,
                doc_title,
                f"/library/document/{document_id}",
            ),
            quote=quote,
            prefix=prefix,
            suffix=suffix,
        )
        _trigger_note_auto_index(
            note_id, service, username, request.session.get("session_id")
        )
        return JSONResponse(
            {
                "success": True,
                "annotation": _annotation_response(
                    note_id, comment, quote, prefix, suffix
                ),
            },
            status_code=201,
        )

    except LookupError:
        return JSONResponse(
            {"success": False, "error": "Document not found"}, status_code=404
        )
    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid annotation data"},
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("creating document annotation", e)


@router.delete("/api/documents/{document_id}/annotations/{note_id}")
@_notes_write_limit
def delete_document_annotation(
    request: Request,
    document_id: str,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Remove a document annotation (deletes the comment note; the
    anchor row cascades)."""
    try:
        service = NoteService(username)
        if not service.has_annotation(note_id, document_id=document_id):
            return JSONResponse(
                {"success": False, "error": "Annotation not found"},
                status_code=404,
            )
        service.delete_note(note_id)
        return {"success": True}

    except Exception as e:
        return handle_api_error("deleting document annotation", e)


# ============================================================================
# API Routes - RAG Indexing
# ============================================================================


@router.post("/api/notes/{note_id}/index")
@_notes_write_limit
def index_note_to_collection(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Index a note into a collection for RAG search.

    Body:
        collection_id: The collection to index the note into (required)
        force_reindex: Whether to force reindexing (optional, default false)
    """
    from ...web.routers.rag import _client_indexing_error, get_rag_service

    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("collection_id"):
            return JSONResponse(
                {"success": False, "error": "collection_id is required"},
                status_code=400,
            )

        collection_id = data["collection_id"]
        # Omitted: defaults to False (do not force-reindex).
        force_reindex = data.get("force_reindex", False)
        if not isinstance(force_reindex, bool):
            logger.warning(
                "notes_api validation reject: force_reindex={} (type={}) "
                "(user={!r})",
                _log_value_preview(force_reindex),
                type(force_reindex).__name__,
                username,
            )
            return JSONResponse(
                {
                    "success": False,
                    "error": "force_reindex must be a boolean",
                },
                status_code=400,
            )

        # Verify the id is actually a note before indexing — every sibling
        # note route guards this, but this one passed the id straight to the
        # RAG service, which would index an arbitrary user document.
        if not NoteService(username).note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        # Get RAG service configured for the collection
        with get_rag_service(request, username, collection_id) as rag_service:
            # Index the note (notes are now documents)
            result = rag_service.index_document(
                document_id=note_id,
                collection_id=collection_id,
                force_reindex=force_reindex,
            )

        if result["status"] == "error":
            # Same boundary as the RAG document routes: known document
            # guidance passes, any other service text is withheld.
            return JSONResponse(
                {
                    "success": False,
                    "error": _client_indexing_error(result.get("error")),
                },
                status_code=400,
            )

        return {"success": True, "result": result}

    except Exception as e:
        return handle_api_error("indexing note", e)


# ============================================================================
# API Routes - AI Features
# (semantic_search_notes is registered above, before GET /api/notes/{note_id})
# ============================================================================


@router.get("/api/notes/{note_id}/similar")
@_notes_search_limit
def get_similar_notes(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """
    Find notes similar to the given note using embeddings.

    Query params:
        limit: Maximum number of results (default 5)
    """
    try:
        try:
            limit = _clamp_limit(request, 5)
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit"}, status_code=400
            )
        # 404 on unknown note id — the AI service returns [] for both a
        # missing note and a note with no similar matches, which made a
        # stale id indistinguishable from a real-empty result. Same guard
        # as get_note_collections / get_note_research.
        if not NoteService(username).note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        service = NoteAIService(username)
        similar = service.find_similar_notes(note_id, limit=limit)

        return {"success": True, "similar_notes": similar}

    except Exception as e:
        return handle_api_error("finding similar notes", e)


@router.post("/api/notes/{note_id}/summarize")
@_notes_ai_limit
async def summarize_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Generate an AI summary of the note."""
    if isinstance(body, JSONResponse):
        return body

    try:
        service = NoteAIService(username)
        summary = await service.summarize_note(note_id)

        # summarize_note returns None only for a missing/empty note (real LLM
        # failures raise → handled below as 500). That's a client/data
        # condition, so 404 — consistent with the sibling AI endpoints.
        if summary is None:
            return JSONResponse(
                {"success": False, "error": "Note not found or empty"},
                status_code=404,
            )

        return {"success": True, "summary": summary}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("summarize")
    except Exception as e:
        return handle_api_error("summarizing note", e)


@router.post("/api/notes/{note_id}/research-questions")
@_notes_ai_limit
async def extract_research_questions(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Extract potential research questions from the note."""
    if isinstance(body, JSONResponse):
        return body

    try:
        # 404 on unknown note id — see get_similar_notes for the rationale.
        if not await run_db_sync(NoteService(username).note_exists, note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        service = NoteAIService(username)
        questions = await service.extract_research_questions(note_id)

        return {"success": True, "questions": questions}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("research-questions")
    except Exception as e:
        return handle_api_error("extracting research questions", e)


@router.post("/api/notes/suggest-tags")
@_notes_ai_limit
async def suggest_tags(
    request: Request,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Suggest tags for note content.

    Body:
        content: The note content to analyze
        existing_tags: Current tags to avoid duplicates (optional)
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("content"):
            return JSONResponse(
                {"success": False, "error": "content is required"},
                status_code=400,
            )

        # Cap body size — same MAX_CONTENT_SIZE used by create_note /
        # update_note. Without this, the route accepts unbounded text and
        # holds it all in memory while the LLM call runs.
        _assert_content_size(data["content"])

        # existing_tags is interpolated/joined downstream; a non-list (or a
        # list with non-string items) would raise deep in the service and
        # surface as an opaque 500. Validate to a clean 400 here.
        existing_tags = data.get("existing_tags")
        if existing_tags is not None and (
            not isinstance(existing_tags, list)
            or not all(isinstance(t, str) for t in existing_tags)
        ):
            return JSONResponse(
                {
                    "success": False,
                    "error": "existing_tags must be a list of strings",
                },
                status_code=400,
            )
        # Cap count + per-item length like _validate_tags does on the
        # create/update paths. suggest_tags joins the WHOLE list before
        # truncating the joined result, so without a cap a client could send a
        # multi-MB existing_tags array (within the body ceiling, at 10/min) and
        # force a large in-memory join on every call.
        if existing_tags is not None and (
            len(existing_tags) > MAX_TAGS_PER_NOTE
            or any(len(t) > MAX_TAG_LENGTH for t in existing_tags)
        ):
            return JSONResponse(
                {
                    "success": False,
                    "error": (
                        f"existing_tags exceeds limits (max "
                        f"{MAX_TAGS_PER_NOTE} tags, {MAX_TAG_LENGTH} chars each)"
                    ),
                },
                status_code=400,
            )

        service = NoteAIService(username)
        tags = await service.suggest_tags(
            content=data["content"],
            existing_tags=existing_tags,
        )

        return {"success": True, "tags": tags}

    except LLMNotConfiguredError:
        # MUST precede the ValueError arm: this is a ValueError subclass, so
        # ordering is what separates "you have not configured a model" from
        # "your request body was invalid" here. See
        # ``_llm_not_configured_response`` for why the answer is a 400 with
        # ``error_type: model_not_configured``.
        return _llm_not_configured_response("suggest-tags")
    except ValueError:
        return JSONResponse(
            {"success": False, "error": "Invalid tag request"},
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("suggesting tags", e)


@router.post("/api/notes/{note_id}/key-concepts")
@_notes_ai_limit
async def extract_key_concepts(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Extract key concepts, entities, and themes from the note."""
    if isinstance(body, JSONResponse):
        return body

    try:
        # 404 on unknown note id — see get_similar_notes for the rationale.
        if not await run_db_sync(NoteService(username).note_exists, note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        service = NoteAIService(username)
        concepts = await service.extract_key_concepts(note_id)

        return {"success": True, "concepts": concepts}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("key-concepts")
    except Exception as e:
        return handle_api_error("extracting key concepts", e)


# ============================================================================
# API Routes - Smart Note Linking
# ============================================================================


@router.get("/api/notes/{note_id}/backlinks")
@_notes_search_limit
def get_backlinks(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get notes that link to this note (backlinks)."""
    try:
        service = NoteService(username)
        # 404 an unknown id like the other note routes, so an empty list
        # for a real note is distinguishable from "no such note".
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        backlinks = service.get_backlinks(note_id)

        return {
            "success": True,
            "backlinks": backlinks,
            "total": len(backlinks),
        }

    except Exception as e:
        return handle_api_error("getting backlinks", e)


@router.get("/api/notes/{note_id}/outgoing-links")
@_notes_search_limit
def get_outgoing_links(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get notes that this note links to."""
    try:
        service = NoteService(username)
        # 404 an unknown id like the other note routes.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        links = service.get_outgoing_links(note_id)

        return {
            "success": True,
            "links": links,
            "total": len(links),
        }

    except Exception as e:
        return handle_api_error("getting outgoing links", e)


@router.get("/api/notes/{note_id}/suggested-links")
@_notes_search_limit
def get_suggested_links(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get AI-suggested notes to link to based on semantic similarity."""
    try:
        try:
            limit = _clamp_limit(request, 5)
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit"}, status_code=400
            )
        # 404 a missing/unknown note like every sibling AI-link route
        # (suggest_links returns [] for a missing note, which is otherwise
        # indistinguishable from "a real note with no suggestions").
        if not NoteService(username).note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        service = NoteAIService(username)
        suggestions = service.suggest_links(note_id, limit=limit)

        return {"success": True, "suggestions": suggestions}

    except Exception as e:
        return handle_api_error("getting suggested links", e)


@router.post("/api/notes/{note_id}/accept-link")
@_notes_write_limit
def accept_suggested_link(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Accept an AI-suggested link: insert [[Target Title]] into the note
    content and flag the resulting NoteLink as auto_suggested=True.

    Body:
        target_note_id: The ID of the note to link to.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        target_note_id = data.get("target_note_id")
        if not target_note_id:
            return JSONResponse(
                {"success": False, "error": "target_note_id required"},
                status_code=400,
            )

        service = NoteService(username)
        result = service.accept_suggested_link(note_id, target_note_id)
        if not result:
            return JSONResponse(
                {"success": False, "error": "Link could not be accepted"},
                status_code=404,
            )

        return {"success": True, "note": result}

    except ValueError:
        return JSONResponse(
            {
                "success": False,
                "error": "Suggested link cannot be accepted",
            },
            status_code=400,
        )
    except Exception as e:
        return handle_api_error("accepting suggested link", e)


@router.get("/api/notes/{note_id}/unlinked-mentions")
@_notes_search_limit
def get_unlinked_mentions(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Notes whose text mentions this note's title but don't yet link to it.

    Lexical (no embeddings). The client links one via the existing
    /accept-link route on the *mentioning* note (target = this note).
    """
    try:
        service = NoteService(username)
        # 404 an unknown id like the other note routes.
        if not service.note_exists(note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )
        mentions = service.get_unlinked_mentions(note_id)
        return {"success": True, "mentions": mentions}
    except Exception as e:
        return handle_api_error("getting unlinked mentions", e)


# Passage text is a paragraph-ish selection; cap it so a huge selection
# can't be sent as the embedding query.
MAX_PASSAGE_LEN = 2000


@router.post("/api/notes/{note_id}/similar-passages")
@_notes_search_limit
def similar_passages(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Find note passages (chunks) semantically similar to a given snippet.

    Body: ``{"text": "<selected paragraph>"}``. Chunks from this note are
    excluded so the result is "related passages elsewhere".
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        text = data.get("text")
        if not text or not isinstance(text, str) or not text.strip():
            return JSONResponse(
                {"success": False, "error": "text required"}, status_code=400
            )
        text = text.strip()[:MAX_PASSAGE_LEN]

        if not NoteService(username).note_exists(note_id):
            logger.warning(
                "notes_api validation reject: similar-passages note_id={} "
                "not found (user={!r})",
                _log_value_preview(note_id),
                username,
            )
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        service = NoteAIService(username)
        passages = service.find_similar_passages(text, exclude_note_id=note_id)
        return {"success": True, "passages": passages}
    except Exception as e:
        return handle_api_error("finding similar passages", e)


# ============================================================================
# API Routes - Ask your notes (research pinned to the Notes collection)
# (ask_context is registered above, before GET /api/notes/{note_id})
# ============================================================================


# ============================================================================
# API Routes - Verify Note with Research (fact-check)
# ============================================================================


@router.post("/api/notes/{note_id}/fact-check")
@_notes_factcheck_limit
async def fact_check_note(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Extract checkable factual claims from a note and synthesize a research
    query for verifying them.

    The client then starts a research run (reusing /api/start_research + the
    research-link flow, exactly like "Research This Note") and, once it
    completes, POSTs the claims to the /grade endpoint below.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        # Guard the note id like every other note route: without this an
        # unknown/typo'd id fell through to the claim-less 422 below, conflating
        # "this note has nothing to verify" with "there is no such note".
        if not await run_db_sync(NoteService(username).note_exists, note_id):
            return JSONResponse(
                {"success": False, "error": "Note not found"}, status_code=404
            )

        ai = NoteAIService(username)
        claims = await ai.extract_claims(note_id)
        if not claims:
            # The note exists but has no checkable factual claims.
            return JSONResponse(
                {
                    "success": False,
                    "error": "No checkable factual claims found in this note.",
                },
                status_code=422,
            )
        query = ai.synthesize_factcheck_query(claims)
        return {"success": True, "claims": claims, "query": query}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("fact-check")
    except Exception as e:
        return handle_api_error("starting note fact-check", e)


async def _grade_note_claims(username, note_id, research_id, claims):
    """Grade ``claims`` against a COMPLETED research run's report and persist
    the verdicts under ``research_meta['fact_check']``.

    Returns a ``(payload, status_code)`` tuple. Extracted from the route so it
    can be unit-tested without a client. DB steps run on worker threads via
    ``run_db_sync`` (thread-local sessions must stay off the event loop —
    #6043), and the LLM grade awaits on the loop so the request thread is
    freed for the length of the model's response (#5854).

    The per-user DB password stays resolvable on those worker threads
    because ``get_user_db_session`` resolves it from the PROCESS-GLOBAL
    ``session_password_store`` (``get_any_session_password(username)``),
    which is neither thread- nor context-bound; the thread-local context
    is only its third fallback, after an explicit ``session_id`` lookup.
    Nothing has to be propagated to the pool here — unlike the
    change-summary executor worker, which is off the request path entirely
    and has the password threaded in explicitly as ``dbpw``.
    """
    from ...constants import ResearchStatus
    from ...database.models import NoteResearch, ResearchHistory
    from ...database.session_context import get_user_db_session
    from ...storage import get_report_storage
    from ..services.report_assembly_service import (
        get_research_source_links_batch,
    )

    def _load_research():
        # Load the research (per-user DB session scopes it to this user) and
        # require it to have completed before grading.
        with get_user_db_session(username) as db:
            research = (
                db.query(ResearchHistory).filter_by(id=research_id).first()
            )
            if not research:
                return None
            # Require the research to actually be linked to THIS note — otherwise a
            # client could grade an arbitrary completed research against an
            # arbitrary note and stamp a foreign note_id into its meta.
            linked = (
                db.query(NoteResearch)
                .filter_by(document_id=note_id, research_id=research_id)
                .first()
            )
            if not linked:
                return False
            return research.status, dict(research.research_meta or {})

    loaded = await run_db_sync(_load_research)
    if loaded is None:
        return {"success": False, "error": "Research not found"}, 404
    if loaded is False:
        return {
            "success": False,
            "error": "Research is not linked to this note",
        }, 404
    status, meta = loaded

    if status != ResearchStatus.COMPLETED:
        return {
            "success": False,
            "error": "Research is not complete yet.",
            "status": status,
        }, 409

    settings_snapshot = meta.get("settings_snapshot")

    def _fetch_report_and_sources():
        # Fetch the report markdown + sources.
        with get_user_db_session(username) as db:
            storage = get_report_storage(
                session=db, settings_snapshot=settings_snapshot
            )
            report = storage.get_report(research_id, username)
            # Sources live in the research_resources table, not research_meta.
            # The post-refactor save path never writes the legacy
            # `all_links_of_system` metadata key (see the identical fix in
            # research_routes.get_report), so reading it here returned [] for
            # every research: the grader prompt always showed "(no sources)"
            # and every verdict's sources array was empty, leaving the
            # citation-validation/anti-rubber-stamp checks unreachable. Read
            # the structured table instead — the same source of truth the
            # results page uses. Fetch only the MAX_GRADE_SOURCES window the
            # grader will actually show; anything past it was discarded.
            sources = get_research_source_links_batch(
                [research_id], db, limit=_MAX_GRADE_SOURCES
            ).get(research_id, [])
        return report, sources

    report, sources = await run_db_sync(_fetch_report_and_sources)

    # get_report returns None for BOTH a missing report and a swallowed read
    # error. Grading against an empty report would label every claim
    # "unverified" and persist that as a successful fact-check — a false result.
    # Refuse to grade instead.
    if not report or not str(report).strip():
        return {
            "success": False,
            "error": (
                "The research report is unavailable, so its claims cannot be "
                "graded. Try re-running the research."
            ),
        }, 502

    ai = NoteAIService(username)
    verdicts = await ai.grade_all_claims(claims, report, sources)

    def _persist_verdicts():
        # Persist verdicts under research_meta['fact_check']. Reassign the whole
        # dict so SQLAlchemy marks the plain-JSON column dirty (this codebase
        # deliberately avoids MutableDict — see research_sources_service.py).
        with get_user_db_session(username) as db:
            research = (
                db.query(ResearchHistory).filter_by(id=research_id).first()
            )
            if research is None:
                # The research row existed when we loaded it for grading (above)
                # but has since vanished — e.g. a concurrent delete between the
                # grade and this persist. The verdicts were computed but cannot be
                # saved. Returning success here would tell the client a fact-check
                # was persisted that never was (a silent partial failure); report
                # the conflict explicitly instead.
                return False
            try:
                new_meta = dict(research.research_meta or {})
                new_meta["fact_check"] = {
                    "note_id": note_id,
                    "claims": claims,
                    "verdicts": verdicts,
                }
                research.research_meta = new_meta
                db.commit()
            except Exception:
                # Don't leave the shared request session poisoned.
                db.rollback()
                raise
        return True

    if not await run_db_sync(_persist_verdicts):
        return {
            "success": False,
            "error": (
                "The research run disappeared before its fact-check "
                "verdicts could be saved. Please try again."
            ),
        }, 409

    return {"success": True, "verdicts": verdicts}, 200


@router.post("/api/notes/{note_id}/fact-check/{research_id}/grade")
@_notes_factcheck_limit
async def grade_note_fact_check(
    request: Request,
    note_id: str,
    research_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Grade a note's claims against a COMPLETED research run's report.

    Body: ``{"claims": ["...", ...]}`` — the claims returned by /fact-check.
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        raw_claims = data.get("claims")
        if not isinstance(raw_claims, list):
            return JSONResponse(
                {"success": False, "error": "claims required"}, status_code=400
            )
        # Cap both the count AND each claim's length — the rest of this file
        # length-bounds free text (MAX_SEARCH_LEN / _clamp_text_query) but the
        # grade endpoint took client claims with no per-string bound.
        claims = [
            c.strip()[:MAX_CLAIM_LEN]
            for c in raw_claims
            if isinstance(c, str) and c.strip()
        ][: NoteAIService.MAX_CLAIMS_PER_NOTE]
        if not claims:
            return JSONResponse(
                {"success": False, "error": "claims required"}, status_code=400
            )

        payload, status_code = await _grade_note_claims(
            username, note_id, research_id, claims
        )
        return JSONResponse(payload, status_code=status_code)

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("fact-check grade")
    except Exception as e:
        return handle_api_error("grading note fact-check", e)


@router.post("/api/notes/resolve-link")
@_notes_search_limit
def resolve_link(
    request: Request,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Resolve a [[link]] text to a note.

    Body:
        link_text: The text inside [[brackets]]
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("link_text"):
            return JSONResponse(
                {"success": False, "error": "link_text is required"},
                status_code=400,
            )
        link_text = data["link_text"]
        # ``_NotesBody`` is a plain parsed-JSON dict with no per-field
        # coercion, so ``link_text`` can be any JSON type. Select the fixed
        # 400 message by TYPE rather than by matching the exception text:
        # ``_clamp_text_query`` raises for two different reasons and only
        # one of them is a length problem, so reporting "exceeds maximum
        # length" for ``{"link_text": 123}`` would be false.
        if not isinstance(link_text, str):
            return JSONResponse(
                {"success": False, "error": "link_text must be a string"},
                status_code=400,
            )
        try:
            link_text = _clamp_text_query(
                link_text, "link_text", max_len=MAX_LINK_TEXT_LEN
            )
        except ValueError:
            return JSONResponse(
                {
                    "success": False,
                    "error": (
                        f"link_text exceeds maximum length "
                        f"({MAX_LINK_TEXT_LEN} chars)"
                    ),
                },
                status_code=400,
            )

        service = NoteService(username)
        result = service.resolve_link(link_text)

        if result:
            return {"success": True, "note": result}
        return JSONResponse(
            {"success": False, "error": "Note not found"}, status_code=404
        )

    except Exception as e:
        return handle_api_error("resolving link", e)


# ============================================================================
# API Routes - Note Synthesis
# ============================================================================


@router.post("/api/notes/synthesize/preview")
@_notes_synthesize_limit
async def preview_synthesis(
    request: Request,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Preview what a synthesis would produce.

    Body:
        note_ids: List of note IDs (2-5)
        synthesis_type: 'merge', 'summarize', or 'compare'
    """
    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("note_ids"):
            return JSONResponse(
                {"success": False, "error": "note_ids is required"},
                status_code=400,
            )

        note_ids = data["note_ids"]
        if not isinstance(note_ids, list) or not all(
            isinstance(n, str) for n in note_ids
        ):
            # Element type matters: synthesize_notes does dict.fromkeys(note_ids),
            # which raises TypeError (→ 500) on unhashable items like dicts.
            return JSONResponse(
                {
                    "success": False,
                    "error": "note_ids must be a list of strings",
                },
                status_code=400,
            )
        synthesis_type = data.get("synthesis_type", "merge")
        # synthesize_notes checks `synthesis_type not in {set}` (a hash), which
        # raises TypeError (→ opaque 500) on an unhashable non-string like a
        # list/dict. Reject to a clean 400 here, like note_ids above.
        if not isinstance(synthesis_type, str):
            return JSONResponse(
                {
                    "success": False,
                    "error": "synthesis_type must be a string",
                },
                status_code=400,
            )

        # synthesize_notes returns the result without saving — callers (this
        # preview route, and the create-note flow downstream) decide whether
        # to persist it. Same call site, same payload.
        service = NoteAIService(username)
        preview = await service.synthesize_notes(note_ids, synthesis_type)

        if "error" in preview:
            return JSONResponse(
                {"success": False, "error": preview["error"]},
                status_code=400,
            )

        return {"success": True, "result": preview}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("synthesize preview")
    except Exception as e:
        return handle_api_error("previewing synthesis", e)


@router.post("/api/notes/synthesize")
@_notes_synthesize_limit
async def synthesize_notes(
    request: Request,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """
    Synthesize multiple notes into one.

    Body:
        note_ids: List of note IDs (2-5)
        synthesis_type: 'merge', 'summarize', or 'compare'
        create_note: Whether to create the note (default true)
    """
    from ...database.models import NoteSynthesis, NoteSynthesisSource

    if isinstance(body, JSONResponse):
        return body

    try:
        data = body
        if not data or not data.get("note_ids"):
            return JSONResponse(
                {"success": False, "error": "note_ids is required"},
                status_code=400,
            )

        note_ids = data["note_ids"]
        if not isinstance(note_ids, list) or not all(
            isinstance(n, str) for n in note_ids
        ):
            # Element type matters: synthesize_notes does dict.fromkeys(note_ids),
            # which raises TypeError (→ 500) on unhashable items like dicts.
            return JSONResponse(
                {
                    "success": False,
                    "error": "note_ids must be a list of strings",
                },
                status_code=400,
            )
        synthesis_type = data.get("synthesis_type", "merge")
        # synthesize_notes checks `synthesis_type not in {set}` (a hash), which
        # raises TypeError (→ opaque 500) on an unhashable non-string like a
        # list/dict. Reject to a clean 400 here, like note_ids above.
        if not isinstance(synthesis_type, str):
            return JSONResponse(
                {
                    "success": False,
                    "error": "synthesis_type must be a string",
                },
                status_code=400,
            )
        # Omitted: defaults to True (persist synthesis as a new note).
        create_note = data.get("create_note", True)
        if not isinstance(create_note, bool):
            logger.warning(
                "notes_api validation reject: create_note={} (type={}) "
                "(user={!r})",
                _log_value_preview(create_note),
                type(create_note).__name__,
                username,
            )
            return JSONResponse(
                {
                    "success": False,
                    "error": "create_note must be a boolean",
                },
                status_code=400,
            )

        ai_service = NoteAIService(username)
        result = await ai_service.synthesize_notes(note_ids, synthesis_type)

        if "error" in result:
            return JSONResponse(
                {"success": False, "error": result["error"]},
                status_code=400,
            )

        # Create the note if requested
        if create_note:
            note_service = NoteService(username)

            def _create_note_and_record_synthesis():
                # Runs on a worker thread via run_db_sync: create_note and
                # the synthesis-record persist both open thread-local DB
                # sessions, which must stay off the event loop (#6043).
                new_note_id = note_service.create_note(
                    title=result["suggested_title"],
                    content=result["content"],
                    tags=["synthesized", synthesis_type],
                )

                # Record the synthesis. Use the FILTERED source set the AI
                # service actually fed to the LLM (result["source_notes"])
                # rather than the raw client input — NoteAIService.synthesize_notes
                # silently drops any non-note Document IDs from the prompt, so
                # persisting raw note_ids would (a) record IDs the LLM never
                # saw as "sources" and (b) FK-violate on any bogus ID after
                # create_note has already committed.
                from ...database.session_context import get_user_db_session

                filtered_source_ids = [
                    src["id"]
                    for src in result.get("source_notes", [])
                    if "id" in src
                ]

                db_session = None
                try:
                    with get_user_db_session(username) as db_session:
                        synthesis_record = NoteSynthesis(
                            result_document_id=new_note_id,
                            synthesis_type=synthesis_type,
                        )
                        for doc_id in filtered_source_ids:
                            synthesis_record.sources.append(
                                NoteSynthesisSource(source_document_id=doc_id)
                            )
                        db_session.add(synthesis_record)
                        db_session.commit()
                except Exception:
                    # create_note() already committed the new Document in its own
                    # session, so a failure here would leave an orphaned
                    # "synthesized" note with no provenance record. Roll back the
                    # poisoned shared session and delete the just-created note
                    # before surfacing the error.
                    logger.exception(
                        "Failed to persist synthesis record for note {}; "
                        "deleting the orphaned note",
                        new_note_id,
                    )
                    NoteService._rollback_quietly(db_session)
                    try:
                        note_service.delete_note(new_note_id)
                    except Exception:
                        logger.exception(
                            "Failed to delete orphaned synthesized note {}",
                            new_note_id,
                        )
                    raise
                return new_note_id

            result["note_id"] = await run_db_sync(
                _create_note_and_record_synthesis
            )

        status_code = 201 if create_note else 200
        return JSONResponse(
            {"success": True, "result": result}, status_code=status_code
        )

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("synthesize")
    except Exception as e:
        return handle_api_error("synthesizing notes", e)


# ============================================================================
# API Routes - Version History
# ============================================================================


@router.get("/api/notes/{note_id}/versions")
def get_note_versions(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """
    Get version history for a note.

    Query params:
        limit: Maximum number of versions to return (default 20, max 200)
        offset: Number of versions to skip (default 0). Combined with
            limit, this makes older versions reachable when total > limit.
            Pre-fix the route had no offset support, so versions 1
            through (total - limit) were unreachable through the UI.
    """
    from ...database.models import Document, NoteVersion
    from ...database.session_context import get_user_db_session

    note_service = NoteService(username)

    try:
        try:
            limit = _clamp_limit(request, 20)
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid limit"}, status_code=400
            )

        try:
            offset = max(0, int(request.query_params.get("offset", 0)))
        except (ValueError, TypeError):
            return JSONResponse(
                {"success": False, "error": "Invalid offset"}, status_code=400
            )

        with get_user_db_session(username) as db_session:
            # Defense-in-depth: confirm the document is a note before
            # serving anything from its version history. Mirrors the
            # guard on the sibling version routes (get_note_version,
            # get_semantic_diff, restore_note_version). load_only keeps
            # the guard from hydrating text_content (up to 50 MB) just
            # to check the source type.
            doc = (
                db_session.query(Document)
                .options(load_only(Document.id, Document.source_type_id))
                .filter_by(id=note_id)
                .first()
            )
            if not doc or not note_service._is_note(db_session, doc):
                return JSONResponse(
                    {"success": False, "error": "Note not found"},
                    status_code=404,
                )

            total = (
                db_session.query(NoteVersion)
                .filter_by(document_id=note_id)
                .count()
            )
            # Cap offset at total: an unbounded OFFSET (e.g.
            # ?offset=1_000_000_000) forces SQLite to row-walk the
            # whole table in a backward index scan even though the
            # result is empty. Clamping is cheap and harmless — a real
            # caller with offset > total wants the empty page anyway.
            if offset > total:
                offset = total
            # Column projection: each NoteVersion row carries a full
            # content snapshot (up to the 50 MB cap); loading whole
            # entities transferred `limit` note bodies per call to render
            # a metadata-only list.
            versions = (
                db_session.query(
                    NoteVersion.id,
                    NoteVersion.title,
                    NoteVersion.change_type,
                    NoteVersion.change_summary,
                    NoteVersion.created_at,
                )
                .filter_by(document_id=note_id)
                .order_by(
                    NoteVersion.created_at.desc(),
                    NoteVersion.id.desc(),  # id tiebreaker for stable paging
                )
                .offset(offset)
                .limit(limit)
                .all()
            )
            return {
                "success": True,
                "total": total,
                "limit": limit,
                "offset": offset,
                "versions": [
                    {
                        "id": v.id,
                        # Global version index — newest is `total`,
                        # oldest is 1. Stable across pages.
                        "version_number": total - offset - i,
                        "title": v.title,
                        "change_type": v.change_type,
                        "change_summary": v.change_summary,
                        "created_at": v.created_at.isoformat()
                        if v.created_at
                        else None,
                    }
                    for i, v in enumerate(versions)
                ],
            }

    except Exception as e:
        return handle_api_error("getting note versions", e)


@router.get("/api/notes/{note_id}/versions/semantic-diff")
@_notes_ai_limit
async def get_semantic_diff(
    request: Request,
    note_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """
    Get AI-powered semantic diff between two versions.

    Query params:
        version1: First version UUID
        version2: Second version UUID, or the literal "current" to diff
                 against the note's current content.
    """
    from ...database.models import Document, NoteVersion
    from ...database.session_context import get_user_db_session

    note_service = NoteService(username)

    try:
        version1 = request.query_params.get("version1")
        version2 = request.query_params.get("version2")

        if not version1 or not version2:
            return JSONResponse(
                {
                    "success": False,
                    "error": "version1 and version2 are required",
                },
                status_code=400,
            )

        def _load_diff_versions():
            # Runs on a worker thread via run_db_sync: the version fetch
            # opens a thread-local DB session, which must stay off the
            # event loop (#6043). Returns ("note"|"version"|None, c1, c2):
            # the first element names the 404 flavor, the strings are the
            # two contents to diff (None when erroring).
            with get_user_db_session(username) as db_session:
                # Defense-in-depth: confirm the document is a note before
                # serving anything from its version history. load_only defers
                # text_content; the "current" branch below lazy-loads it only
                # when actually diffing against the live note.
                doc = (
                    db_session.query(Document)
                    .options(load_only(Document.id, Document.source_type_id))
                    .filter_by(id=note_id)
                    .first()
                )
                if not doc or not note_service._is_note(db_session, doc):
                    return "note", None, None

                v1 = (
                    db_session.query(NoteVersion)
                    .filter_by(document_id=note_id, id=version1)
                    .first()
                )
                if not v1:
                    return "version", None, None

                if version2 == "current":
                    return None, v1.content, doc.text_content or ""

                v2 = (
                    db_session.query(NoteVersion)
                    .filter_by(document_id=note_id, id=version2)
                    .first()
                )
                if not v2:
                    return "version", None, None
                return None, v1.content, v2.content

        missing, v1_content, v2_content = await run_db_sync(_load_diff_versions)
        if missing == "note":
            return JSONResponse(
                {"success": False, "error": "Note not found"},
                status_code=404,
            )
        if missing == "version":
            return JSONResponse(
                {"success": False, "error": "Version not found"},
                status_code=404,
            )

        ai_service = NoteAIService(username)
        diff = await ai_service.semantic_diff(v1_content, v2_content)

        return {"success": True, "diff": diff}

    except LLMNotConfiguredError:
        # Same contract as suggest-tags: an unconfigured LLM is a
        # client-state problem, not a 500. See
        # ``_llm_not_configured_response``.
        return _llm_not_configured_response("semantic-diff")
    except Exception as e:
        return handle_api_error("getting semantic diff", e)


@router.get("/api/notes/{note_id}/versions/{version_id}")
def get_note_version(
    request: Request,
    note_id: str,
    version_id: str,
    username: Annotated[str, Depends(require_auth)],
):
    """Get a specific version of a note."""
    from ...database.models import Document, NoteVersion
    from ...database.session_context import get_user_db_session

    note_service = NoteService(username)

    try:
        with get_user_db_session(username) as db_session:
            # Defense-in-depth: confirm the parent document is a note.
            # load_only keeps the guard from hydrating text_content.
            doc = (
                db_session.query(Document)
                .options(load_only(Document.id, Document.source_type_id))
                .filter_by(id=note_id)
                .first()
            )
            if not doc or not note_service._is_note(db_session, doc):
                return JSONResponse(
                    {"success": False, "error": "Note not found"},
                    status_code=404,
                )

            version = (
                db_session.query(NoteVersion)
                .filter_by(document_id=note_id, id=version_id)
                .first()
            )

            if not version:
                return JSONResponse(
                    {"success": False, "error": "Version not found"},
                    status_code=404,
                )

            return {
                "success": True,
                "version": {
                    "id": version.id,
                    "title": version.title,
                    "content": version.content,
                    "tags": version.tags,
                    "change_type": version.change_type,
                    "change_summary": version.change_summary,
                    "created_at": version.created_at.isoformat()
                    if version.created_at
                    else None,
                },
            }

    except Exception as e:
        return handle_api_error("getting note version", e)


@router.post("/api/notes/{note_id}/versions/{version_id}/restore")
@_notes_write_limit
def restore_note_version(
    request: Request,
    note_id: str,
    version_id: str,
    username: Annotated[str, Depends(require_auth)],
    body: _NotesBody,
):
    """Restore a note to a previous version.

    Delegates to ``NoteService.restore_with_bookends`` which wraps
    PRE_RESTORE + content update + RESTORE in a single transaction.
    Earlier code orchestrated this from three separate sessions — process
    death between writes could leave a restored note with no audit-trail
    row. Keep the orchestration in the service; this handler just routes.
    """
    if isinstance(body, JSONResponse):
        return body

    note_service = NoteService(username)

    try:
        success, error = note_service.restore_with_bookends(note_id, version_id)
        if not success:
            if error == "note_not_found":
                return JSONResponse(
                    {"success": False, "error": "Note not found"},
                    status_code=404,
                )
            if error == "version_not_found":
                return JSONResponse(
                    {"success": False, "error": "Version not found"},
                    status_code=404,
                )
            return JSONResponse(
                {"success": False, "error": "Failed to restore version"},
                status_code=500,
            )

        _trigger_note_auto_index(
            note_id, note_service, username, request.session.get("session_id")
        )

        return {
            "success": True,
            "message": f"Restored to version {version_id[:8]}",
        }

    except Exception as e:
        return handle_api_error("restoring note version", e)