Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

33.9 KB
Raw Blame
"""Unit tests for the cumulative source inventory used by the chat capability."""

from __future__ import annotations

from typing import Any

import pytest

from deeptutor.reading.references import ResolvedReadingSource
from deeptutor.services.session.source_inventory import (
    SourceEntry,
    SourceInventory,
    build_inventory,
    collect_prior_image_attachments,
    render_manifest,
    serialize_referenced_transcript,
)


class FakeStore:
    """Minimal store fake covering the protocol methods source_inventory
    actually calls: get_messages, get_session, get_messages_for_context,
    get_notebook_entry. Tests inject the data they want via constructor."""

    def __init__(
        self,
        *,
        messages: list[dict[str, Any]] | None = None,
        sessions: dict[str, dict[str, Any]] | None = None,
        session_messages: dict[str, list[dict[str, Any]]] | None = None,
        notebook_entries: dict[int, dict[str, Any]] | None = None,
    ) -> None:
        self._messages = messages or []
        self._sessions = sessions or {}
        self._session_messages = session_messages or {}
        self._notebook_entries = notebook_entries or {}

    async def get_messages(self, session_id: str) -> list[dict[str, Any]]:
        return self._messages

    async def get_session(self, session_id: str) -> dict[str, Any] | None:
        return self._sessions.get(session_id)

    async def get_messages_for_context(
        self, session_id: str, leaf_message_id: int | None = None
    ) -> list[dict[str, Any]]:
        return self._session_messages.get(session_id, [])

    async def get_notebook_entry(self, entry_id: int) -> dict[str, Any] | None:
        return self._notebook_entries.get(entry_id)


# ---------------------------------------------------------------------------
# SourceInventory dataclass
# ---------------------------------------------------------------------------


def test_inventory_dedupe_fresh_wins() -> None:
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="at-foo",
            kind="attachment",
            name="old",
            full_text="old text",
            fresh=False,
            first_seen_turn=1,
        )
    )
    inv.add(
        SourceEntry(
            sid="at-foo",
            kind="attachment",
            name="fresh",
            full_text="fresh text",
            fresh=True,
            first_seen_turn=2,
        )
    )
    assert len(inv.entries) == 1
    assert inv.entries[0].fresh is True
    assert inv.entries[0].name == "fresh"


def test_inventory_skips_empty_text() -> None:
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="at-foo",
            kind="attachment",
            name="empty",
            full_text="   ",
            fresh=True,
            first_seen_turn=1,
        )
    )
    assert inv.is_empty()


def test_inventory_preserves_insertion_order() -> None:
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="a", kind="attachment", name="A", full_text="A", fresh=True, first_seen_turn=1
        )
    )
    inv.add(
        SourceEntry(
            sid="b", kind="attachment", name="B", full_text="B", fresh=False, first_seen_turn=1
        )
    )
    inv.add(
        SourceEntry(
            sid="c", kind="notebook", name="C", full_text="C", fresh=True, first_seen_turn=1
        )
    )
    assert [e.sid for e in inv.entries] == ["a", "b", "c"]


# ---------------------------------------------------------------------------
# render_manifest
# ---------------------------------------------------------------------------


def test_render_manifest_empty() -> None:
    text, idx = render_manifest(SourceInventory())
    assert text == ""
    assert idx == {}


def test_render_manifest_distinguishes_fresh_vs_historical() -> None:
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="at-fresh",
            kind="attachment",
            name="new.pdf",
            full_text="hello world",
            fresh=True,
            first_seen_turn=3,
        )
    )
    inv.add(
        SourceEntry(
            sid="at-old",
            kind="attachment",
            name="old.pdf",
            full_text="x" * 5000,
            fresh=False,
            first_seen_turn=1,
        )
    )
    text, idx = render_manifest(inv)
    # Fresh row carries a preview field
    assert "preview:" in text
    assert "'hello world'" in text
    # Historical row carries "previously attached (turn 1)" with no preview
    assert "previously attached (turn 1)" in text
    assert "size=" in text
    # source_index has full text for both
    assert idx["at-fresh"] == "hello world"
    assert idx["at-old"] == "x" * 5000


def test_render_manifest_does_not_advertise_answer_loop_source_tools() -> None:
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="at-old",
            kind="attachment",
            name="homework.pdf",
            full_text="PDF body",
            fresh=False,
            first_seen_turn=1,
        )
    )
    text, _ = render_manifest(inv)
    assert "Context Investigator" in text
    assert "call a file/PDF tool" in text
    assert "loaded on demand" not in text


# ---------------------------------------------------------------------------
# build_inventory
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_build_inventory_fresh_attachments_only() -> None:
    store = FakeStore()
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=1,
        fresh_attachment_records=[
            {"id": "a1", "type": "pdf", "filename": "x.pdf", "extracted_text": "PDF body"},
            {"id": "img", "type": "image", "filename": "p.png", "extracted_text": ""},  # skipped
        ],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    assert [e.sid for e in inv.entries] == ["at-a1"]
    assert inv.entries[0].fresh is True


@pytest.mark.asyncio
async def test_partner_group_reference_is_a_structured_bounded_source(monkeypatch) -> None:
    from deeptutor.services import partner_groups as partner_groups_service

    calls: list[tuple[str, str, str]] = []

    class FakeGroups:
        def referenced_transcript(self, group_id, session_key, *, language):
            calls.append((group_id, session_key, language))
            return (
                "[Partner Group]\nAda: public answer\nBob: another public answer",
                "Study panel: First question",
            )

    monkeypatch.setattr(
        partner_groups_service,
        "get_partner_group_manager",
        lambda: FakeGroups(),
    )
    inv = await build_inventory(
        FakeStore(),
        session_id="home-session",
        leaf_message_id=None,
        current_turn_ordinal=1,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
        fresh_partner_group_references=[
            {"group_id": "study-panel", "session_key": "pg-thread"},
            {"group_id": "", "session_key": "ignored"},
        ],
        language="zh",
    )

    assert calls == [("study-panel", "pg-thread", "zh")]
    assert len(inv.entries) == 1
    assert inv.entries[0].sid.startswith("pg-")
    assert inv.entries[0].kind == "partner_group"
    assert inv.entries[0].name == "Study panel: First question"
    assert "Ada: public answer" in inv.entries[0].full_text


def test_partner_group_reference_request_contract_is_normalized_and_snapshotted() -> None:
    from deeptutor.services.session.turn_runtime import (
        _partner_group_references,
        _request_snapshot_metadata,
    )

    references = _partner_group_references(
        [
            {"group_id": " study-panel ", "session_key": " thread-a "},
            {"group_id": "study-panel", "session_key": "thread-a"},
            {"group_id": "", "session_key": "ignored"},
        ]
    )
    assert references == [{"group_id": "study-panel", "session_key": "thread-a"}]

    metadata = _request_snapshot_metadata(
        payload={},
        content="Use the attached panel",
        capability="chat",
        config={},
        attachments=[],
        notebook_references=[],
        history_references=[],
        partner_group_references=references,
        question_notebook_references=[],
        book_references=[],
        persona="",
        memory_references=[],
        llm_selection=None,
    )
    assert metadata["request_snapshot"]["partnerGroupReferences"] == references


@pytest.mark.asyncio
async def test_build_inventory_historical_attachment_visible_to_next_turn() -> None:
    """Attachment uploaded in turn 1 must appear as 'previously attached
    (turn 1)' in turn 2's manifest, even though turn 2's payload is empty."""
    past = [
        {
            "id": 1,
            "role": "user",
            "content": "first message",
            "parent_message_id": None,
            "attachments": [
                {
                    "id": "att-1",
                    "filename": "year1-1.pdf",
                    "extracted_text": "lecture notes",
                    "mime_type": "application/pdf",
                }
            ],
            "metadata": {"request_snapshot": {}},
        },
        {
            "id": 2,
            "role": "assistant",
            "content": "ok",
            "parent_message_id": 1,
            "attachments": [],
            "metadata": {},
        },
    ]
    store = FakeStore(messages=past)
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,  # legacy linear; lineage walker returns all
        current_turn_ordinal=2,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    assert [e.sid for e in inv.entries] == ["at-att-1"]
    e = inv.entries[0]
    assert e.fresh is False
    assert e.first_seen_turn == 1
    assert e.full_text == "lecture notes"


@pytest.mark.asyncio
async def test_build_inventory_branch_isolated() -> None:
    """Branch B should not see attachments uploaded in a sibling branch A."""
    # Layout:
    #   1 (user, root) → 2 (assistant) → 3 (user, branch A, attaches X.pdf)
    #                                  → 4 (user, branch B, attaches Y.pdf)
    # When we ask for branch B (leaf=4), only 1, 2, 4 are in lineage.
    msgs = [
        {
            "id": 1,
            "role": "user",
            "content": "q1",
            "parent_message_id": None,
            "attachments": [],
            "metadata": {"request_snapshot": {}},
        },
        {
            "id": 2,
            "role": "assistant",
            "content": "a1",
            "parent_message_id": 1,
            "attachments": [],
            "metadata": {},
        },
        {
            "id": 3,
            "role": "user",
            "content": "branch A",
            "parent_message_id": 2,
            "attachments": [
                {
                    "id": "X",
                    "filename": "X.pdf",
                    "extracted_text": "branchA only",
                    "mime_type": "application/pdf",
                }
            ],
            "metadata": {"request_snapshot": {}},
        },
        {
            "id": 4,
            "role": "user",
            "content": "branch B",
            "parent_message_id": 2,
            "attachments": [
                {
                    "id": "Y",
                    "filename": "Y.pdf",
                    "extracted_text": "branchB only",
                    "mime_type": "application/pdf",
                }
            ],
            "metadata": {"request_snapshot": {}},
        },
    ]
    store = FakeStore(messages=msgs)
    # Render branch B's inventory (leaf=4) — should see Y, not X.
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=4,
        current_turn_ordinal=3,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    sids = [e.sid for e in inv.entries]
    assert "at-Y" in sids, sids
    assert "at-X" not in sids, sids


@pytest.mark.asyncio
async def test_build_inventory_fresh_shadows_historical_on_same_sid() -> None:
    """If a notebook record is referenced both in a past turn and this
    turn, the manifest shows it as fresh (with preview), not historical."""
    msgs = [
        {
            "id": 1,
            "role": "user",
            "content": "earlier",
            "parent_message_id": None,
            "attachments": [],
            "metadata": {"request_snapshot": {}},
        },
    ]
    store = FakeStore(messages=msgs)
    # Fresh record matching what historical *would have* added if it had
    # one — but historical lineage has empty snap, so only fresh is added.
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=2,
        fresh_attachment_records=[
            {
                "id": "att-1",
                "filename": "f.pdf",
                "extracted_text": "fresh body",
                "mime_type": "application/pdf",
            }
        ],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    assert inv.entries[0].fresh is True
    assert inv.entries[0].full_text == "fresh body"


@pytest.mark.asyncio
async def test_build_inventory_adds_server_resolved_reading_units(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from deeptutor.reading import references

    seen: list[dict[str, Any]] = []

    def resolve(refs: list[dict[str, Any]]) -> list[ResolvedReadingSource]:
        seen.extend(refs)
        return [
            ResolvedReadingSource(
                source_id="rd-abcdef0123456789-r3-2",
                name="Source book — Chapter 2",
                full_text="trusted chapter text",
            )
        ]

    monkeypatch.setattr(references, "resolve_reading_sources", resolve)
    inv = await build_inventory(
        FakeStore(),
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=1,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
        fresh_reading_references=[
            {"material_id": "abcdef0123456789", "revision": 3, "locators": [2]}
        ],
    )

    assert seen == [{"material_id": "abcdef0123456789", "revision": 3, "locators": [2]}]
    assert inv.entries[0].sid == "rd-abcdef0123456789-r3-2"
    assert inv.entries[0].kind == "reading"
    assert inv.entries[0].fresh is True


@pytest.mark.asyncio
async def test_historical_reading_units_are_re_resolved_from_snapshot(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from deeptutor.reading import references

    monkeypatch.setattr(
        references,
        "resolve_reading_sources",
        lambda refs: (
            [
                ResolvedReadingSource(
                    source_id="rd-abcdef0123456789-r2-1",
                    name="Source book — Chapter 1",
                    full_text="current stored chapter text",
                )
            ]
            if refs
            else []
        ),
    )
    store = FakeStore(
        messages=[
            {
                "id": 1,
                "role": "user",
                "parent_message_id": None,
                "attachments": [],
                "metadata": {
                    "request_snapshot": {
                        "readingReferences": [
                            {
                                "material_id": "abcdef0123456789",
                                "revision": 2,
                                "locators": [1],
                            }
                        ]
                    }
                },
            }
        ]
    )

    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=2,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )

    assert inv.entries[0].fresh is False
    assert inv.entries[0].full_text == "current stored chapter text"


# ---------------------------------------------------------------------------
# serialize_referenced_transcript — identity framing (the "floor" fix)
# ---------------------------------------------------------------------------


def test_serialize_imported_transcript_frames_as_external_agent() -> None:
    """An imported session must read as a THIRD-PARTY conversation: the
    assistant turns carry the external agent's name (not '## Assistant'), and
    a boundary header tells the model it did not take part."""
    meta = {
        "session_id": "imported_claude_code_abc",
        "title": "更新页眉导航模型",
        "preferences": {"import": {"source": "claude_code"}},
    }
    messages = [
        {"role": "user", "content": "更新导航"},
        {"role": "assistant", "content": "我已通过代码注入完成了修改。"},
    ]
    out = serialize_referenced_transcript(meta, messages, language="en")
    assert "Claude Code" in out
    assert "## Claude Code" in out  # assistant turns relabelled to the agent
    assert "## Assistant" not in out  # never the model's own role label
    assert "## User" in out
    assert "did not take part" in out.lower()


def test_serialize_imported_transcript_zh_labels_and_framing() -> None:
    meta = {
        "session_id": "imported_codex_x",
        "preferences": {"import": {"source": "codex"}},
    }
    out = serialize_referenced_transcript(
        meta, [{"role": "assistant", "content": "done"}], language="zh"
    )
    assert "Codex" in out
    assert "## Codex" in out
    assert "第三方" in out or "不是你" in out


def test_serialize_native_referenced_transcript_frames_as_separate() -> None:
    """A referenced *native* session keeps the Assistant label but is framed
    as a separate conversation, not the current one."""
    meta = {"session_id": "unified_123", "title": "Past chat"}
    messages = [
        {"role": "user", "content": "q"},
        {"role": "assistant", "content": "a"},
    ]
    out = serialize_referenced_transcript(meta, messages, language="en")
    assert "separate past conversation" in out.lower()
    assert "## Assistant" in out
    assert "## User" in out


def test_serialize_imported_detected_by_prefix_without_import_meta() -> None:
    """The ``imported_`` id prefix alone marks a session external even when the
    preferences block is absent; the label falls back to a generic agent."""
    meta = {"session_id": "imported_claude_code_zzz"}
    out = serialize_referenced_transcript(
        meta, [{"role": "assistant", "content": "x"}], language="en"
    )
    assert "an external AI assistant" in out
    assert "## an external AI assistant" in out


def test_serialize_returns_empty_when_no_content() -> None:
    meta = {"session_id": "imported_x"}
    assert serialize_referenced_transcript(meta, [{"role": "user", "content": "  "}]) == ""
    assert serialize_referenced_transcript(meta, []) == ""


# ---------------------------------------------------------------------------
# Partner session references (partner:{pid}:{session_key})
# ---------------------------------------------------------------------------


def test_serialize_partner_transcript_uses_partner_name() -> None:
    """A partner transcript is framed as a third party under the partner's own
    name (not the generic 'external AI assistant')."""
    meta = {"preferences": {"import": {"source": "partner"}}, "partner_name": "Panda Kate"}
    out = serialize_referenced_transcript(
        meta, [{"role": "assistant", "content": "hi"}], language="en"
    )
    assert "Panda Kate" in out
    assert "## Panda Kate" in out


class _FakePartnerManager:
    def __init__(self, *, exists=True, messages=None, name="Panda Kate") -> None:
        self._exists = exists
        self._messages = messages or []
        self._name = name

    def partner_exists(self, pid):
        return self._exists

    def get_history(self, pid, *, session_key, limit=100):
        return list(self._messages)

    def load_config(self, pid):
        cfg = type("Cfg", (), {})()
        cfg.name = self._name
        return cfg


def _patch_partner(monkeypatch, manager, *, is_admin=True):
    import deeptutor.multi_user.context as ctx
    import deeptutor.services.partners as partners_pkg

    monkeypatch.setattr(partners_pkg, "get_partner_manager", lambda: manager)
    user = type("U", (), {"is_admin": is_admin})()
    monkeypatch.setattr(ctx, "get_current_user", lambda: user)


@pytest.mark.asyncio
async def test_load_history_session_resolves_partner_reference(monkeypatch) -> None:
    from deeptutor.services.session.source_inventory import _load_history_session

    manager = _FakePartnerManager(
        messages=[
            {"role": "user", "content": "我最近做了什么"},
            {"role": "assistant", "content": "你最近在配置 DeepTutor。"},
        ]
    )
    _patch_partner(monkeypatch, manager, is_admin=True)

    # The session_key itself contains a colon (web:abc) — only the pid is split.
    text, title = await _load_history_session(
        FakeStore(), "partner:panda-kate:web:abc", language="zh"
    )
    assert "Panda Kate" in text  # framed under the partner's name
    assert "我最近做了什么" in text
    assert title == "我最近做了什么"


@pytest.mark.asyncio
async def test_load_history_session_partner_blocked_for_non_admin(monkeypatch) -> None:
    from deeptutor.services.session.source_inventory import _load_history_session

    manager = _FakePartnerManager(messages=[{"role": "user", "content": "secret"}])
    _patch_partner(monkeypatch, manager, is_admin=False)

    text, title = await _load_history_session(FakeStore(), "partner:paul:dt-1", language="en")
    assert text == "" and title == ""  # partner data is admin-scoped


@pytest.mark.asyncio
async def test_load_history_session_partner_missing_returns_empty(monkeypatch) -> None:
    from deeptutor.services.session.source_inventory import _load_history_session

    manager = _FakePartnerManager(exists=False)
    _patch_partner(monkeypatch, manager, is_admin=True)

    text, _ = await _load_history_session(FakeStore(), "partner:ghost:dt-1")
    assert text == ""


# ---------------------------------------------------------------------------
# Prior-image collection (#1438: images are the one attachment kind with no
# cross-turn path — the manifest excludes them and multimodal blocks exist
# only on the upload turn).
# ---------------------------------------------------------------------------


@pytest.mark.asyncio
async def test_collect_prior_images_returns_branch_images_most_recent_first() -> None:
    messages = [
        {
            "id": 1,
            "role": "user",
            "content": "first",
            "parent_message_id": None,
            "attachments": [
                {
                    "id": "img-1",
                    "type": "image",
                    "filename": "first.png",
                    "mime_type": "image/png",
                    "url": "/files/attachments/s1/img-1/first.png",
                }
            ],
        },
        {"id": 2, "role": "assistant", "content": "ok", "parent_message_id": 1, "attachments": []},
        {
            "id": 3,
            "role": "user",
            "content": "second",
            "parent_message_id": 2,
            "attachments": [
                {
                    "id": "img-2",
                    "type": "image",
                    "filename": "second.png",
                    "mime_type": "image/png",
                    "url": "/files/attachments/s1/img-2/second.png",
                }
            ],
        },
    ]
    store = FakeStore(messages=messages)

    collected = await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None)

    assert [entry["id"] for entry in collected] == ["img-2", "img-1"]
    assert all(entry["type"] == "image" for entry in collected)
    assert collected[0]["url"].endswith("second.png")


@pytest.mark.asyncio
async def test_collect_prior_images_skips_non_images_and_url_less_entries() -> None:
    messages = [
        {
            "id": 1,
            "role": "user",
            "content": "first",
            "parent_message_id": None,
            "attachments": [
                {
                    "id": "doc-1",
                    "filename": "notes.pdf",
                    "mime_type": "application/pdf",
                    "url": "/files/attachments/s1/doc-1/notes.pdf",
                },
                {
                    "id": "img-nourl",
                    "type": "image",
                    "filename": "legacy.png",
                    "mime_type": "image/png",
                    "url": "",
                },
            ],
        }
    ]
    store = FakeStore(messages=messages)

    collected = await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None)

    assert collected == []


@pytest.mark.asyncio
async def test_collect_prior_images_dedupes_and_excludes_current_ids() -> None:
    messages = [
        {
            "id": 1,
            "role": "user",
            "content": "first",
            "parent_message_id": None,
            "attachments": [
                {
                    "id": "img-1",
                    "type": "image",
                    "filename": "shot.png",
                    "mime_type": "image/png",
                    "url": "/files/attachments/s1/img-1/shot.png",
                }
            ],
        },
        {
            "id": 2,
            "role": "user",
            "content": "again",
            "parent_message_id": 1,
            "attachments": [
                {
                    "id": "img-1",
                    "type": "image",
                    "filename": "shot.png",
                    "mime_type": "image/png",
                    "url": "/files/attachments/s1/img-1/shot.png",
                }
            ],
        },
    ]
    store = FakeStore(messages=messages)

    collected = await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None)
    assert [entry["id"] for entry in collected] == ["img-1"]

    reattached = await collect_prior_image_attachments(
        store,
        session_id="s1",
        leaf_message_id=None,
        exclude_urls={"/files/attachments/s1/img-1/shot.png"},
    )
    assert reattached == []


@pytest.mark.asyncio
async def test_collect_prior_images_caps_at_limit() -> None:
    messages = [
        {
            "id": idx + 1,
            "role": "user" if idx % 2 == 0 else "assistant",
            "content": f"m{idx}",
            "parent_message_id": None if idx == 0 else idx,
            "attachments": (
                [
                    {
                        "id": f"img-{idx}",
                        "type": "image",
                        "filename": f"shot-{idx}.png",
                        "mime_type": "image/png",
                        "url": f"/files/attachments/s1/img-{idx}/shot-{idx}.png",
                    }
                ]
                if idx % 2 == 0
                else []
            ),
        }
        for idx in range(10)
    ]
    store = FakeStore(messages=messages)

    collected = await collect_prior_image_attachments(
        store, session_id="s1", leaf_message_id=None, limit=3
    )

    assert [entry["id"] for entry in collected] == ["img-8", "img-6", "img-4"]


# ---------------------------------------------------------------------------
# Unavailable-attachment surfacing (#1438 expected behavior 6: a file whose
# text extraction produced nothing must show a reason in the manifest instead
# of being silently skipped — a silent skip is why the model asks the learner
# to re-upload without ever saying why).
# ---------------------------------------------------------------------------


def test_inventory_accepts_note_only_entries() -> None:
    """An entry with no text but an availability reason is kept."""
    inv = SourceInventory()
    inv.add(
        SourceEntry(
            sid="at-foo",
            kind="attachment",
            name="scan.pdf",
            full_text="   ",
            fresh=True,
            first_seen_turn=1,
            availability_note="text extraction produced no content",
        )
    )
    assert not inv.is_empty()


@pytest.mark.asyncio
async def test_fresh_attachment_without_extracted_text_shows_a_reason() -> None:
    store = FakeStore(messages=[])
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=1,
        fresh_attachment_records=[
            {
                "id": "att-scan",
                "type": "file",
                "filename": "scan.pdf",
                "mime_type": "application/pdf",
                "extracted_text": "",
            }
        ],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    manifest, source_index = render_manifest(inv)

    # The row exists so the model can name the file and say why it cannot
    # quote it — instead of silently pretending nothing was attached.
    assert "at-att-scan" in manifest
    assert "scan.pdf" in manifest
    assert "extraction" in manifest
    # But there is no full text to serve: the sid must not advertise itself
    # as readable through read_source.
    assert "at-att-scan" not in source_index


@pytest.mark.asyncio
async def test_historical_attachment_without_extracted_text_shows_a_reason() -> None:
    messages = [
        {
            "id": 1,
            "role": "user",
            "content": "first",
            "parent_message_id": None,
            "attachments": [
                {
                    "id": "att-old",
                    "filename": "scanned.pdf",
                    "extracted_text": "",
                    "mime_type": "application/pdf",
                }
            ],
            "metadata": {"request_snapshot": {}},
        }
    ]
    store = FakeStore(messages=messages)
    inv = await build_inventory(
        store,
        session_id="s1",
        leaf_message_id=None,
        current_turn_ordinal=2,
        fresh_attachment_records=[],
        fresh_notebook_records=[],
        fresh_book_context_text="",
        fresh_book_references=[],
        fresh_history_session_ids=[],
        fresh_question_entry_ids=[],
    )
    manifest, source_index = render_manifest(inv)

    assert "at-att-old" in manifest
    assert "extraction" in manifest
    assert "at-att-old" not in source_index


def _image_messages(count: int) -> list[dict[str, Any]]:
    return [
        {
            "id": index,
            "role": "user",
            "attachments": [
                {
                    "id": f"img-{index}",
                    "type": "image",
                    "filename": f"{index}.png",
                    "mime_type": "image/png",
                    "url": f"/files/attachments/s1/img-{index}/{index}.png",
                }
            ],
        }
        for index in range(1, count + 1)
    ]


@pytest.mark.asyncio
async def test_prior_image_reinjection_is_bounded_by_system_settings(monkeypatch) -> None:
    """The cap is deployment policy, not a number frozen into the collector.

    Every later turn re-sends what this returns, so an operator whose model or
    bandwidth cannot afford four images has to be able to say so.
    """
    store = FakeStore(messages=_image_messages(6))
    monkeypatch.setattr(
        "deeptutor.services.config.get_prior_image_reinject_limit",
        lambda: 2,
    )

    collected = await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None)

    assert [entry["id"] for entry in collected] == ["img-6", "img-5"]


@pytest.mark.asyncio
async def test_a_zero_limit_turns_prior_image_reinjection_off(monkeypatch) -> None:
    """0 is a real setting: no re-injection, and no lineage read to do it."""
    store = FakeStore(messages=_image_messages(3))
    monkeypatch.setattr(
        "deeptutor.services.config.get_prior_image_reinject_limit",
        lambda: 0,
    )

    assert await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None) == []


@pytest.mark.asyncio
async def test_a_system_json_written_before_this_knob_existed_still_reinjects(
    monkeypatch,
) -> None:
    """Every upgraded install has one, and it must not take the feature down.

    Reading the knob by subscript turned a missing key into a KeyError raised
    from inside turn setup, which surfaced as unrelated session tests failing.
    """
    from deeptutor.services.config import runtime_settings

    monkeypatch.setattr(
        runtime_settings,
        "load_system_settings",
        lambda: {"chat_attachment_max_file_mb": 20},
    )
    store = FakeStore(messages=_image_messages(2))

    collected = await collect_prior_image_attachments(store, session_id="s1", leaf_message_id=None)

    assert [entry["id"] for entry in collected] == ["img-2", "img-1"]


def test_the_reinject_cap_is_clamped_into_a_sane_range() -> None:
    from deeptutor.services.config.runtime_settings import (
        CHAT_PRIOR_IMAGE_REINJECT_RANGE,
        DEFAULT_SYSTEM_SETTINGS,
    )

    low, high = CHAT_PRIOR_IMAGE_REINJECT_RANGE
    assert low == 0, "0 must stay reachable: it is how the feature is turned off"
    assert low <= DEFAULT_SYSTEM_SETTINGS["chat_prior_image_reinject_max"] <= high