brain-of-reese/tests/unit/test_kb_tree_builder.py

"""Unit tests: ``app.api.docs.build_kb_tree`` (phase 97, task 02).

The PURE tree builder behind ``GET /api/docs/tree`` — the RAG view's
drill-down tree, the same tree the agent's ``ls`` walks plus file
metadata. Driven without a database (module-level function, plain
inputs): multi-source ordering (the superset rule), the 0-document
registered source, the nested recursive counts, the phase-94 existence
rule, the file/folder name collision, ordering, summaries, verbatim
file metadata, and the ``group_folder_listing`` cross-check property
("the UI shows what the agent sees") at the root and one nested level.
"""
from __future__ import annotations

from app.api.docs import TreeDocRow, build_kb_tree
from app.rag.agent import group_folder_listing

T0 = "2026-09-01T08:00:00+00:00"
T1 = "2026-09-02T08:00:00+00:00"
T2 = "2026-09-03T08:00:00+00:00"

# Phase 106 (task 05): the 6th catalogue element — the document's
# creation date (``created_at``, ISO-8601). Deliberately DISTINCT from
# the ``indexed_at`` stamps so a test that confuses the two columns
# fails loudly.
C0 = "2020-01-01T00:00:00+00:00"
C1 = "2021-06-15T12:00:00+00:00"
C2 = "2022-03-01T06:00:00+00:00"
C3 = "2023-11-30T23:59:59+00:00"


def _folder_nodes(node) -> list:
    """The folder-kind children of a source/folder node, in order."""
    return [child for child in node.children if child.kind == "folder"]


def _file_nodes(node) -> list:
    """The file-kind children of a source/folder node, in order."""
    return [child for child in node.children if child.kind == "file"]


def test_multi_source_registry_order_leads_and_indexed_only_appended() -> None:
    """Sources = the registry names in order, then the distinct
    indexed-only sources in alphabetical order (the superset rule)."""
    names = ["beta", "alpha", "empty"]  # registry order — NOT alphabetical
    doc_rows: list[TreeDocRow] = [
        ("beta", "b.md", "B", 1, T0, C0),
        ("alpha", "a.md", "A", 1, T0, C0),
        ("gamma", "g.md", "G", 1, T0, C0),  # indexed-only → appended
        ("delta", "d.md", "D", 1, T0, C0),  # indexed-only → appended
    ]
    tree = build_kb_tree(names, doc_rows, {})
    assert [s.name for s in tree] == ["beta", "alpha", "empty", "delta", "gamma"]
    # The registry sources keep their registry order even though it is
    # not alphabetical; the indexed-only ones trail, sorted.
    assert tree[0].name == "beta"
    assert tree[1].name == "alpha"
    assert tree[3].name == "delta"
    assert tree[4].name == "gamma"


def test_registered_zero_document_source_lists_empty() -> None:
    """A registered source with no indexed documents lists (the
    phase-70/72 invariant): ``documents: 0``, no children, summary null
    when nothing is stored."""
    tree = build_kb_tree(["solo"], [], {})
    assert len(tree) == 1
    assert tree[0].name == "solo"
    assert tree[0].documents == 0
    assert tree[0].children == []
    assert tree[0].summary is None
    # Phase 106 (D9): a 0-document source has no dates at all.
    assert tree[0].updated_at is None


def test_nested_document_counts_into_source_ancestors_and_own_folder() -> None:
    """A document under ``a/b/c/`` contributes to the source, to ``a``,
    to ``a/b``, and to ``a/b/c`` (the recursive subtree, the phase-94
    ``ls`` count rule)."""
    rows = [
        ("S", "a/b/c/deep.md", "Deep", 1, T0, C0),
        ("S", "a/b/shallow.md", "Shallow", 1, T0, C0),
        ("S", "a/top.md", "Top", 1, T0, C0),
        ("S", "root.md", "Root", 1, T0, C0),
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    assert source.documents == 4
    a = _folder_nodes(source)[0]
    assert a.path == "a"
    assert a.documents == 3  # deep + shallow + top
    a_b = _folder_nodes(a)[0]
    assert a_b.path == "a/b"
    assert a_b.documents == 2  # deep + shallow
    a_b_c = _folder_nodes(a_b)[0]
    assert a_b_c.path == "a/b/c"
    assert a_b_c.documents == 1  # deep only
    assert [f.path for f in _file_nodes(a_b_c)] == ["a/b/c/deep.md"]
    assert [f.path for f in _file_nodes(a)] == ["a/top.md"]


def test_existence_rule_a_file_path_is_never_a_folder() -> None:
    """A folder node appears only with a true descendant (some path
    starts with ``folder + "/"``); a document's own path — even one
    with dots — never creates a folder."""
    rows = [
        ("S", "x.md", "X", 1, T0, C0),
        ("S", "x.y/z.md", "Z", 1, T0, C1),
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    folders = _folder_nodes(source)
    # Only ``x.y`` exists (``x.y/z.md`` starts with ``x.y/``); ``x`` and
    # ``x.md`` are file names, not folders.
    assert [f.path for f in folders] == ["x.y"]
    assert [f.path for f in _file_nodes(source)] == ["x.md"]
    assert [f.path for f in _file_nodes(folders[0])] == ["x.y/z.md"]


def test_file_folder_name_collision_both_appear() -> None:
    """A document sharing a directory's name: BOTH appear — the folder
    node (via its descendants) and the file node (its own row); the
    colliding file counts into the folder's subtree (the ``ls`` count
    rule's ``path == folder`` arm)."""
    rows = [
        ("S", "a", "File A", 1, T0, C0),  # a file wearing the folder's name
        ("S", "a/b.md", "B", 1, T0, C1),  # makes ``a`` a folder
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    folders = _folder_nodes(source)
    files = _file_nodes(source)
    assert [f.path for f in folders] == ["a"]
    assert folders[0].documents == 2  # "a" itself + "a/b.md"
    assert [f.path for f in files] == ["a"]
    assert files[0].title == "File A"
    assert [f.path for f in _file_nodes(folders[0])] == ["a/b.md"]


def test_subfolder_path_order_and_file_catalog_order() -> None:
    """Direct subfolders list in path (sorted) order; direct files keep
    the input (catalog — ``GET /api/docs``) order, independent of the
    subfolder ordering."""
    rows = [
        ("S", "zeta/z1.md", "Z1", 1, T0, C0),
        ("S", "alpha/a1.md", "A1", 1, T0, C0),
        ("S", "mike/m1.md", "M1", 1, T0, C0),
        ("S", "beta/b1.md", "B1", 1, T0, C0),
        ("S", "z-file.md", "Z", 1, T0, C0),  # file AFTER the folders in input
        ("S", "a-file.md", "A", 1, T0, C0),  # file before it in input
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    assert [f.path for f in _folder_nodes(source)] == ["alpha", "beta", "mike", "zeta"]
    # Input order is preserved for the files (z-file.md precedes
    # a-file.md in the input, so it does too here — catalog order is
    # the INPUT order, not a re-sort).
    assert [f.path for f in _file_nodes(source)] == ["z-file.md", "a-file.md"]


def test_summaries_present_and_absent() -> None:
    """``summary`` is the stored row (source root ``""`` or folder
    path) or null when absent — any row (AI or manual is indistinguishable
    here; the builder carries whatever is stored)."""
    rows = [
        ("S", "one/a.md", "A", 1, T0, C0),
        ("S", "one/b.md", "B", 1, T0, C0),
        ("S", "two/c.md", "C", 1, T0, C0),
    ]
    summaries = {("S", ""): "Source desc.", ("S", "one"): "One desc."}
    # ("S", "two") is NOT stored → null.
    (source,) = build_kb_tree(["S"], rows, summaries)
    assert source.summary == "Source desc."
    one, two = _folder_nodes(source)
    assert one.summary == "One desc."
    assert two.summary is None
    # File nodes carry no summary key at all on the WIRE (the
    # 00_phase.md shape — the model_dump set check below is the wire
    # pin); since phase 106 they DO carry the creation date
    # (``created_at`` — the RAG view's ``Created`` column).
    file = _file_nodes(one)[0]
    assert set(file.model_dump()) == {
        "kind", "path", "title", "chunks", "created_at", "indexed_at"
    }
    # Phase 122 (task 04): the image-affordance fields DO exist on the
    # class now (image file nodes set them — the wire omission for text
    # nodes is the ``KbTreeFile`` serializer, pinned by the model_dump
    # set check above: a text node never leaks the three keys).
    from app.schemas import KbTreeFile

    assert {"is_image", "image_url", "summary"} <= set(KbTreeFile.model_fields)


def test_file_metadata_unchanged_in_tree() -> None:
    """File ``title`` / ``chunks`` / ``created_at`` (phase 106) /
    ``indexed_at`` ride into the tree verbatim from the catalogue row
    (no reformatting) — and the two stamps stay distinct (the
    ``created_at`` date is not confused with the ``indexed_at`` stamp)."""
    rows = [("S", "deep/x/y.md", "The Title", 7, T2, C2)]
    (source,) = build_kb_tree(["S"], rows, {})
    file = _file_nodes(_folder_nodes(_folder_nodes(source)[0])[0])[0]
    assert file.path == "deep/x/y.md"
    assert file.title == "The Title"
    assert file.chunks == 7
    assert file.created_at == C2  # phase 106: verbatim from the catalogue row
    assert file.indexed_at == T2


def test_empty_inputs_empty_tree() -> None:
    """No registry sources and no indexed documents → an empty tree
    (the RAG view's ``{"sources": []}`` case)."""
    assert build_kb_tree([], [], {}) == []


def test_indexed_document_under_unlisted_source_is_impossible() -> None:
    """By construction (the superset rule) every doc source is listed —
    the registry names lead and every other doc source follows; there
    is no input where a document is dropped."""
    names = ["reg-b", "reg-a"]
    rows: list[TreeDocRow] = [
        ("reg-b", "b.md", "B", 1, T0, C0),
        ("zzz", "z.md", "Z", 1, T0, C1),
        ("aaa", "a.md", "A", 1, T0, C2),
        ("reg-a", "a.md", "A2", 1, T0, C3),
    ]
    tree = build_kb_tree(names, rows, {})
    listed = [s.name for s in tree]
    assert listed == ["reg-b", "reg-a", "aaa", "zzz"]
    doc_paths = {
        f.path for s in tree for f in s.children if f.kind == "file"
    }
    # Every document from the input is present exactly once.
    assert doc_paths == {"b.md", "z.md", "a.md"}
    assert sum(s.documents for s in tree) == len(rows)


# --------------------------------------------------------------------
# The cross-check property — "the UI shows what the agent sees":
# for a single-source dataset the builder's level equals
# ``app.rag.agent.group_folder_listing``'s output.
# --------------------------------------------------------------------

#: The shared single-source dataset: nested folders, root files, a
#: summary-stored folder and an unstored one. Paths are in (source,
#: path) catalog order; titles map 1:1 to paths.
CROSS_ROWS: list[TreeDocRow] = [
    ("S", "note", "Note", 1, T0, C0),
    ("S", "one/a.md", "A", 2, T1, C1),
    ("S", "one/b.md", "B", 0, T1, C1),
    ("S", "one/two/c.md", "C", 3, T1, C2),
    ("S", "one/two/d.md", "D", 1, T1, C2),
    ("S", "root.md", "Root", 4, T0, C3),
    ("S", "zz/e.md", "E", 2, T2, C0),
    ("S", "zz/f.md", "F", 2, T2, C0),
]

CROSS_SUMMARIES = {
    ("S", ""): "Source desc.",
    ("S", "one"): "One desc.",
    ("S", "zz"): "Zz desc.",
    # ("S", "one/two") deliberately unstored → null at that level.
}


def _cross_check(folder: str, builder_node) -> None:
    """Assert the builder's level *folder* equals
    ``group_folder_listing("S", folder, ...)`` — same subfolder
    ``(path, count, summary)`` triples in order AND same file
    ``(source, path, title, date)`` 4-tuples in order (uncapped — the
    dataset is well under the ``ls`` 50-line cap, so the cap is inert).
    Phase 106 (task 06, D5): the cross-check compares the builder's
    OUTPUT node projections against the agent's extended file shape —
    the node's ``created_at`` DATE PART (the same ``YYYY-MM-DD`` the
    agent's ``ls`` line renders) joins the comparison.
    """
    rows = [
        (path, title, created[:10])
        for _source, path, title, _chunks, _stamp, created in CROSS_ROWS
    ]
    source_summaries = {
        folder_path: summary
        for (source, folder_path), summary in CROSS_SUMMARIES.items()
        if source == "S"
    }
    subs, files, _total = group_folder_listing("S", folder, rows, source_summaries)
    assert [(f.path, f.documents, f.summary) for f in _folder_nodes(builder_node)] == subs
    assert [(f.path, f.title, f.created_at[:10]) for f in _file_nodes(builder_node)] == [
        (path, title, date) for _source, path, title, date in files
    ]


def test_cross_check_root_level_matches_group_folder_listing() -> None:
    """At the source root the builder's direct subfolders / direct
    files equal the agent's root level, element for element."""
    (source,) = build_kb_tree(["S"], CROSS_ROWS, CROSS_SUMMARIES)
    _cross_check("", source)
    # And the explicit expectations (the test is readable without the
    # helper): one → 4 docs (its whole subtree), zz → 2.
    assert source.documents == 8
    assert [(f.path, f.documents, f.summary) for f in _folder_nodes(source)] == [
        ("one", 4, "One desc."),
        ("zz", 2, "Zz desc."),
    ]
    assert [(f.path, f.title) for f in _file_nodes(source)] == [
        ("note", "Note"),
        ("root.md", "Root"),
    ]


def test_cross_check_nested_level_matches_group_folder_listing() -> None:
    """One nested level (``one``): subfolder ``one/two`` (2 docs, no
    stored summary) + the direct files ``one/a.md`` / ``one/b.md`` —
    equal to the agent's drill into the same folder."""
    (source,) = build_kb_tree(["S"], CROSS_ROWS, CROSS_SUMMARIES)
    one = next(f for f in _folder_nodes(source) if f.path == "one")
    _cross_check("one", one)
    assert [(f.path, f.documents, f.summary) for f in _folder_nodes(one)] == [
        ("one/two", 2, None),
    ]
    assert [(f.path, f.title) for f in _file_nodes(one)] == [
        ("one/a.md", "A"),
        ("one/b.md", "B"),
    ]


# --------------------------------------------------------------------
# summary_pending (phase 98, task 03) — the D3 rule (ONE concept):
# a SOURCE or FOLDER node is pending iff its recursive document count
# ≥ MIN_DOCS_PER_FOLDER (1) AND it has NO stored folder_summaries row
# (AI or manual — any row). That is exactly
# ``app.rag.folder_summaries.missing_folder_summaries``'s candidate
# set — the marker never drifts from the gap-fill (the integration
# cross-check in ``tests/integration/test_docs_api.py`` pins it
# end to end). FILE nodes carry no flag.
# --------------------------------------------------------------------


def test_folder_two_docs_no_stored_row_is_pending() -> None:
    """A ≥ 2-doc folder with NO stored row → ``summary_pending`` true
    (the marker's "waiting to generate" semantics); file nodes carry
    no flag at all (the file table has no description column)."""
    rows = [
        ("S", "one/a.md", "A", 1, T0, C0),
        ("S", "one/b.md", "B", 1, T0, C0),
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    (one,) = _folder_nodes(source)
    assert one.documents == 2
    assert one.summary is None
    assert one.summary_pending is True
    file = _file_nodes(one)[0]
    assert "summary_pending" not in file.__class__.model_fields
    assert "summary_pending" not in file.model_dump()


def test_folder_with_stored_row_is_not_pending() -> None:
    """The same ≥ 2-doc folder WITH a stored row — ANY row, the builder
    cannot tell AI from manual — is NOT pending (a description exists).
    A row on the folder does not cover the source root: with no
    ``(source, "")`` row the SOURCE node stays pending."""
    rows = [
        ("S", "one/a.md", "A", 1, T0, C0),
        ("S", "one/b.md", "B", 1, T0, C0),
    ]
    (source,) = build_kb_tree(["S"], rows, {("S", "one"): "Manual."})
    (one,) = _folder_nodes(source)
    assert one.summary == "Manual."
    assert one.summary_pending is False
    # The source root (2 docs) has no (source, "") row of its own.
    assert source.summary is None
    assert source.summary_pending is True


def test_single_document_folder_is_pending() -> None:
    """The ≥ 1 rule: a 1-document folder with NO stored row IS pending
    (its one file line no longer exempts it — the next sync
    summarizes it), as is its source root (2 docs, no root row).
    A registered 0-document source is the only never-pending case."""
    rows = [
        ("S", "solo/only.md", "Only", 1, T0, C0),  # 1-doc folder
        ("S", "top.md", "Top", 1, T0, C1),  # source total = 2
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    (solo,) = _folder_nodes(source)
    assert solo.documents == 1
    assert solo.summary_pending is True
    assert source.summary_pending is True


def test_name_collision_pending_follows_recursive_count() -> None:
    """The phase-94 count-rule edge: documents ``one/a`` AND ``one/a/b``
    → folder ``one/a`` exists and its recursive count is 2 (the document
    whose path EQUALS the folder name counts — the ``path == folder``
    arm) → pending true with no stored row, even though the folder has
    only ONE direct file — pending follows the RECURSIVE count, not
    the number of direct children. A stored row on the NESTED folder
    alone clears only that marker (the rule is per node)."""
    rows = [
        ("S", "one/a", "File A", 1, T0, C0),  # a file wearing the folder's name
        ("S", "one/a/b.md", "B", 1, T0, C1),  # makes ``one/a`` a folder
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    one = _folder_nodes(source)[0]
    assert one.path == "one"
    assert one.documents == 2
    assert one.summary_pending is True
    a = _folder_nodes(one)[0]
    assert a.path == "one/a"
    assert a.documents == 2  # "one/a" itself + "one/a/b.md"
    assert len(_file_nodes(a)) == 1  # ONE direct file — the count is not that
    assert a.summary_pending is True
    # Stored row on the nested folder only: it clears that node, and
    # only that node.
    (nested,) = build_kb_tree(["S"], rows, {("S", "one/a"): "Nested."})
    one2 = _folder_nodes(nested)[0]
    a2 = _folder_nodes(one2)[0]
    assert a2.summary == "Nested."
    assert a2.summary_pending is False
    assert one2.summary_pending is True


def test_source_root_pending_and_zero_document_source_never() -> None:
    """The source root: a source with ≥ 1 docs and NO ``(source, "")``
    row → the SOURCE node is pending; the stored root row clears it.
    A registered 0-document source is NEVER pending (0 < the minimum —
    there is nothing to summarize), with or without a manual row."""
    rows = [
        ("Full", "x/1.md", "1", 1, T0, C0),
        ("Full", "y.md", "Y", 1, T0, C1),
    ]
    full, empty = build_kb_tree(["Full", "Empty"], rows, {})
    assert full.documents == 2
    assert full.summary_pending is True
    assert empty.documents == 0
    assert empty.summary_pending is False
    full2, empty2 = build_kb_tree(
        ["Full", "Empty"], rows, {("Full", ""): "Root desc."}
    )
    assert full2.summary == "Root desc."
    assert full2.summary_pending is False
    assert empty2.summary_pending is False


def test_two_sources_pending_independently() -> None:
    """Pending is computed per source: with one source holding a root
    row and the other not, only the rowless source's node is pending —
    the markers never leak across sources."""
    rows = [
        ("A", "a1.md", "A1", 1, T0, C0),
        ("A", "a2.md", "A2", 1, T0, C1),
        ("B", "b1.md", "B1", 1, T0, C2),
        ("B", "b2.md", "B2", 1, T0, C3),
    ]
    a, b = build_kb_tree(["A", "B"], rows, {("A", ""): "A root."})
    assert (a.summary, a.summary_pending) == ("A root.", False)
    assert (b.summary, b.summary_pending) == (None, True)


# --------------------------------------------------------------------
# Document dates (phase 106, task 05, D8/D9) — the pure builder's date
# threading: file ``created_at`` verbatim; folder/source ``updated_at``
# = the subtree's MAX document ``created_at`` (derived as the builder
# recurses, never stored; ``None`` for a node with no documents).
# --------------------------------------------------------------------


def test_updated_at_deep_file_beats_shallow_sibling() -> None:
    """D9: a folder's ``updated_at`` is the MAX over its WHOLE subtree —
    a deeper file's date wins over a shallower sibling's (the max
    recurses through every level, not just the direct files)."""
    rows = [
        ("S", "root.md", "Root", 1, T0, C0),
        ("S", "a/top.md", "Top", 1, T0, C1),
        ("S", "a/b/shallow.md", "Shallow", 1, T0, C2),
        ("S", "a/b/c/deep.md", "Deep", 1, T0, C3),  # the overall max
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    a = _folder_nodes(source)[0]
    a_b = _folder_nodes(a)[0]
    a_b_c = _folder_nodes(a_b)[0]
    # The deepest folder: its one file's date.
    assert a_b_c.updated_at == C3
    # a/b: its own file (C2) vs its child's subtree max (C3) → C3.
    assert a_b.updated_at == C3
    # a: its direct file (C1) vs the deeper subtree (C3) → the DEEPER
    # file's date wins over the shallow sibling's.
    assert a.updated_at == C3
    # The source root: max over root.md (C0) + a's subtree (C3).
    assert source.updated_at == C3
    # File nodes carry their own date verbatim — no ``updated_at`` key.
    deep = _file_nodes(a_b_c)[0]
    assert deep.created_at == C3
    assert "updated_at" not in deep.model_dump()


def test_updated_at_direct_file_wins_when_it_is_the_max() -> None:
    """The inverse: when a folder's OWN direct file holds the newest
    date, the max stays at the direct level (the recursion takes the
    max, it does not prefer depth)."""
    rows = [
        ("S", "root.md", "Root", 1, T0, C0),
        ("S", "a/top.md", "Top", 1, T0, C3),  # the overall max, DIRECT
        ("S", "a/b/shallow.md", "Shallow", 1, T0, C1),
        ("S", "a/b/c/deep.md", "Deep", 1, T0, C2),
    ]
    (source,) = build_kb_tree(["S"], rows, {})
    a = _folder_nodes(source)[0]
    a_b = _folder_nodes(a)[0]
    a_b_c = _folder_nodes(a_b)[0]
    assert a_b_c.updated_at == C2  # its own file
    assert a_b.updated_at == C2  # max(C1, child C2)
    assert a.updated_at == C3  # the direct file (C3) beats the subtree (C2)
    assert source.updated_at == C3  # max(C0, a's C3)


def test_updated_at_threads_through_folder_only_subtree() -> None:
    """A folder with NO direct files (only subfolders) still carries the
    date threaded up from its child subfolders — the max is over the
    children (files AND folders), so a pure directory chain never loses
    the dates below it."""
    rows = [("S", "a/b/c/x.md", "X", 1, T0, C2)]
    (source,) = build_kb_tree(["S"], rows, {})
    a = _folder_nodes(source)[0]  # no direct files — only subfolder a/b
    a_b = _folder_nodes(a)[0]  # no direct files — only subfolder a/b/c
    a_b_c = _folder_nodes(a_b)[0]
    assert a_b_c.updated_at == C2
    assert a_b.updated_at == C2
    assert a.updated_at == C2
    assert source.updated_at == C2


def test_updated_at_is_none_only_for_nodes_without_documents() -> None:
    """``None`` is reserved for nodes with NO documents at all — a
    registered 0-document source; every node that has ≥ 1 document in
    its subtree carries a date (the 6th catalogue element is always
    present — ``created_at`` is NOT NULL, D1)."""
    full, empty = build_kb_tree(
        ["Full", "Empty"],
        [("Full", "only.md", "Only", 1, T0, C1)],
        {},
    )
    assert full.documents == 1
    assert full.updated_at == C1
    assert empty.documents == 0
    assert empty.updated_at is None
    assert empty.children == []


def test_updated_at_does_not_leak_across_sources() -> None:
    """The max is per source subtree: one source's newest document never
    lifts another source's ``updated_at`` (the dates are computed
    inside :func:`build_kb_tree`'s per-source node, like ``documents``
    and ``summary_pending``)."""
    rows = [
        ("A", "a1.md", "A1", 1, T0, C0),
        ("B", "b1.md", "B1", 1, T0, C3),  # B's date is the global max
    ]
    a, b = build_kb_tree(["A", "B"], rows, {})
    assert a.updated_at == C0
    assert b.updated_at == C3


# ---------------------------------------------------------------------------
# Phase 122 (task 04) — the image-docs affordance on tree file nodes
# ---------------------------------------------------------------------------

DOC_ID = "11111111-2222-3333-4444-555555555555"


def test_image_file_node_carries_the_affordance_and_text_node_unchanged() -> None:
    """The ``images`` map (``{(source, path): (doc_id, summary)}``) turns
    a file node into the image-docs node: ``is_image`` true,
    ``image_url`` = the bytes route's path built from the mapped id,
    ``summary`` verbatim (the RAG view's thumbnail ``alt``). A file
    node NOT in the map keeps the pre-phase wire shape byte-identically
    (the three image keys are OMITTED, not false/null)."""
    rows = [
        ("S", "one/a.md", "A", 1, T0, C0),
        ("S", "one/pic.png", "pic", 2, T0, C0),
    ]
    images = {("S", "one/pic.png"): (DOC_ID, "A red square on a white background.")}
    (source,) = build_kb_tree(["S"], rows, {}, images)
    one = _folder_nodes(source)[0]
    # File nodes keep the FULL source-relative path (the phase-97
    # shape — the folder prefix rides the node).
    files = {f.path: f for f in _file_nodes(one)}

    # Text node: the pre-phase wire shape, byte-identical (no image keys).
    assert set(files["one/a.md"].model_dump()) == {
        "kind", "path", "title", "chunks", "created_at", "indexed_at"
    }

    # Image node: the affordance rides the node.
    dumped = files["one/pic.png"].model_dump()
    assert dumped["kind"] == "file"
    assert dumped["is_image"] is True
    assert dumped["image_url"] == f"/api/documents/{DOC_ID}/image"
    assert dumped["summary"] == "A red square on a white background."
    # The catalogue fields still ride verbatim.
    assert (dumped["title"], dumped["chunks"]) == ("pic", 2)
    assert (dumped["created_at"], dumped["indexed_at"]) == (C0, T0)


def test_image_file_node_null_summary_and_missing_map_entry() -> None:
    """A mapped image node with a NULL summary (the fail-soft backfill
    corner) keeps ``summary: null`` on the wire (meaningful — the alt
    falls back client-side). A map entry that points at a NON-existent
    (source, path) affects nothing (the builder only reads mapped keys
    it meets in the catalogue rows)."""
    rows = [
        ("S", "one/ghost.png", "ghost", 1, T0, C0),
        ("S", "one/other.md", "Other", 1, T0, C0),
    ]
    images = {
        ("S", "one/ghost.png"): (DOC_ID, None),
        ("S", "one/absent.png"): (DOC_ID, "never matched"),
    }
    (source,) = build_kb_tree(["S"], rows, {}, images)
    one = _folder_nodes(source)[0]
    files = {f.path: f for f in _file_nodes(one)}
    ghost = files["one/ghost.png"].model_dump()
    assert ghost["is_image"] is True
    assert ghost["summary"] is None  # null stays (the alt fallback corner)
    assert ghost["image_url"] == f"/api/documents/{DOC_ID}/image"
    assert set(files["one/other.md"].model_dump()) == {
        "kind", "path", "title", "chunks", "created_at", "indexed_at"
    }


def test_image_affordance_absent_without_the_map() -> None:
    """No map (the default) → every file node is the pre-phase shape,
    even for ``.png`` paths: the fields are map-driven (the endpoint
    composes the map from the ``is_image`` rows), never path-guessed —
    a pre-phase KB serializes byte-identically."""
    rows = [("S", "pic.png", "pic", 1, T0, C0)]
    (source,) = build_kb_tree(["S"], rows, {})
    (file,) = _file_nodes(source)
    assert set(file.model_dump()) == {
        "kind", "path", "title", "chunks", "created_at", "indexed_at"
    }