llm-ingestion-okf/tests/test_link_line_signal.py

"""The door's own link line, and whether the ranker should read it.

`inbox._link_enclosing` appends ONE line to a heading-only body:
`Enclosing section: [<title>](/<bundle-absolute path>)`. SPEC SS 6.1 makes the
absolute form the recommended one, and that argument is about the FILE. Nothing
ever decided that the line should also be scored: `consume._body` returns
everything after the frontmatter, so the line reaches the body signal, the
lexical gate and the excerpt alike -- and the path repeats the document's own
directory in every linked body, which is the saturation round 20 took OUT of
the id signal (`shared_id_prefix`).

This file gives `consume` the instrument that separates the two readings on ONE
bundle: the line stays in the file and stays in the excerpt a reader gets, and
`link_in_signal=False` keeps it out of the SIGNAL alone. K3-23 measured with it
and recommended it; since K3-25 it is the DEFAULT reading, and `True` is the
reading a caller now has to ask for.

The recognition is the DOOR's, not a regex over prose: `inbox.ENCLOSING_SECTION`
plus the link's own shape, in the one place the door writes it -- last in the
body, after a blank line. The two known-negatives below are what that buys: a
human line opening with the same two words, and the door's exact form somewhere
other than last, both keep every character they have.
"""

from __future__ import annotations

import sys
from pathlib import Path

PROJECT_ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(PROJECT_ROOT / "tools"))

import okf_consume  # noqa: E402

from llm_ingestion_okf.inbox import ENCLOSING_SECTION  # noqa: E402

QUESTION = "Hvilke krav gjelder for sikringsbolter?"

_FRONTMATTER = (
    "---\ntype: reference\ntitle: {title}\nsource_file: r761.xml\n"
    "source_sha256: {digest}\ningested_at: 2026-09-01T00:00:00Z\n"
    "adjudication: proposed\nbundle_id: link-fixture\n"
    "verified: [{{ by: process:okf-check, at: 2026-09-01T00:00:00Z }}]\n---\n\n"
)

#: Exactly what the door writes, built from the door's own constant so a rename
#: there breaks this file rather than silently loosening the rule.
DOOR_LINE = f"{ENCLOSING_SECTION}: [Sikringsbolter](/r761/33-2/sikringsbolter.md)"


def _bundle(root: Path) -> Path:
    """One document: three concepts, and only the link line names the question.

    The shell's own text is its heading, and its heading does NOT carry the
    question's token -- so every lexical hit it has comes from the door's line.
    The two known-negatives carry text that merely LOOKS like the line.
    """
    (root / "r761").mkdir(parents=True)
    (root / "index.md").write_text(
        "---\nokf_version: 0.2\nbundle_id: link-fixture\n---\n\n- [r761 (index)](r761/index.md)\n",
        encoding="utf-8",
    )
    entries: list[str] = []

    def add(slug: str, title: str, body: str) -> None:
        entries.append(f"- [{title}]({slug}.md) — adjudication: proposed\n")
        (root / "r761" / f"{slug}.md").write_text(
            _FRONTMATTER.format(title=title, digest="1" * 64) + body,
            encoding="utf-8",
        )

    # The shell, as the door leaves it: heading, blank line, one link.
    add("skall", "33.212 Boltetype B", f"## 33.212 Boltetype B\n\n{DOOR_LINE}\n")
    # KNOWN-NEGATIVE 1: a human sentence opening with the same two words.
    add(
        "menneske",
        "33.213 Boltetype C",
        "## 33.213 Boltetype C\n\nEnclosing section: se kapittelet om sikringsbolter.\n",
    )
    # KNOWN-NEGATIVE 2: the door's exact form, but not last in the body.
    add(
        "midt",
        "33.214 Boltetype D",
        f"## 33.214 Boltetype D\n\n{DOOR_LINE}\n\nDenne teksten staar under lenka.\n",
    )
    (root / "r761" / "index.md").write_text("".join(entries), encoding="utf-8")
    return root


def _lexical(root: Path, *, link_in_signal: bool) -> dict[str, int]:
    """Each concept's own lexical overlap, the third member of the ranked tuple."""
    concepts = [
        okf_consume.read_concept(
            root / f"{concept_id}.md", bundle_root=root, root_bundle_id="link-fixture"
        )
        for concept_id in okf_consume.enumerate_concepts(root)
    ]
    ranked = okf_consume.concept_scores(
        concepts,
        QUESTION,
        okf_consume.document_scores(root, QUESTION),
        link_in_signal=link_in_signal,
    )
    return {concept.concept_id: lexical for concept, _, lexical in ranked}


# --- What the line does to the signal today -----------------------------------


def test_the_doors_line_is_the_shells_only_lexical_hit_today(tmp_path: Path) -> None:
    """CHARACTERISATION, green before the instrument exists.

    The shell's own text answers nothing in the question, and it still scores --
    on the line the door wrote. It takes no new parameter to show, which is why
    it is asked without one: the mechanism is HEAD's behaviour, not the fix's.
    """
    root = _bundle(tmp_path / "bundle")
    concepts = [
        okf_consume.read_concept(
            root / f"{concept_id}.md", bundle_root=root, root_bundle_id="link-fixture"
        )
        for concept_id in okf_consume.enumerate_concepts(root)
    ]
    ranked = okf_consume.concept_scores(
        concepts, QUESTION, okf_consume.document_scores(root, QUESTION)
    )
    scored = {concept.concept_id: lexical for concept, _, lexical in ranked}
    assert scored["r761/skall"] > 0


def test_the_instrument_takes_the_line_out_of_the_signal(tmp_path: Path) -> None:
    root = _bundle(tmp_path / "bundle")
    # Two different numbers, not one predicate read twice.
    assert _lexical(root, link_in_signal=True)["r761/skall"] == 1
    assert _lexical(root, link_in_signal=False)["r761/skall"] == 0


def test_both_readings_run_on_the_same_concept_objects(tmp_path: Path) -> None:
    """One bundle, two readings, in one process -- never two builds compared."""
    root = _bundle(tmp_path / "bundle")
    concepts = [
        okf_consume.read_concept(
            root / f"{concept_id}.md", bundle_root=root, root_bundle_id="link-fixture"
        )
        for concept_id in okf_consume.enumerate_concepts(root)
    ]
    prior = okf_consume.document_scores(root, QUESTION)
    with_line = okf_consume.concept_scores(concepts, QUESTION, prior, link_in_signal=True)
    without = okf_consume.concept_scores(concepts, QUESTION, prior, link_in_signal=False)
    assert with_line != without
    # The instrument reads; it does not edit what it measures.
    shell = next(c for c in concepts if c.concept_id == "r761/skall")
    assert DOOR_LINE in shell.body


# --- The two known-negatives, both obligatory ---------------------------------


def test_a_human_line_opening_with_the_same_two_words_is_not_stripped(tmp_path: Path) -> None:
    root = _bundle(tmp_path / "bundle")
    on = _lexical(root, link_in_signal=False)
    off = _lexical(root, link_in_signal=True)
    assert off["r761/menneske"] == on["r761/menneske"] > 0


def test_the_doors_form_anywhere_but_last_is_not_stripped(tmp_path: Path) -> None:
    root = _bundle(tmp_path / "bundle")
    on = _lexical(root, link_in_signal=False)
    off = _lexical(root, link_in_signal=True)
    assert off["r761/midt"] == on["r761/midt"] > 0


def test_the_stripper_leaves_a_body_that_never_had_a_link(tmp_path: Path) -> None:
    body = "## 33.9 Noe annet\n\nHer staar det tekst.\n"
    assert okf_consume.body_without_link_line(body) == body


def test_the_stripper_removes_the_line_and_the_blank_line_before_it() -> None:
    body = f"## 33.212 Boltetype B\n\n{DOOR_LINE}\n"
    assert okf_consume.body_without_link_line(body) == "## 33.212 Boltetype B\n"


# --- The payload is untouched --------------------------------------------------


def test_the_excerpt_still_carries_the_line_the_reader_needs(tmp_path: Path) -> None:
    """The file keeps it, the reader keeps it; only the signal looks away."""
    root = _bundle(tmp_path / "bundle")
    payload = okf_consume.build_payload(root, question=QUESTION, link_in_signal=False)
    texts = [str(excerpt["text"]) for excerpt in payload["excerpts"]]  # type: ignore[index]
    assert any(DOOR_LINE in text for text in texts)


def test_the_default_payload_is_the_reading_without_the_line(tmp_path: Path) -> None:
    """K3-23 shipped the instrument OFF; K3-25 made it the default.

    The assertion is the same shape and the other side of it: a payload built
    with no parameter is the one built with `link_in_signal=False`, and the
    reading K3-23 defaulted to is now the one a caller names.
    """
    root = _bundle(tmp_path / "bundle")
    implicit = okf_consume.serialise(okf_consume.build_payload(root, question=QUESTION))
    explicit = okf_consume.serialise(
        okf_consume.build_payload(root, question=QUESTION, link_in_signal=False)
    )
    assert implicit == explicit


# --- K3-25: the reading WITHOUT the line becomes the default ------------------
#
# K3-23 measured the whole decomposition and landed on one recommendation: the
# cost is the PATH, not the link. 39 of 39 newcomers that won a question token
# from the door's line won it through the bundle-absolute path and 0 of 39
# through the link's title, and every token the path ever contributed is a
# segment of the document's own directory -- exactly the saturation
# `shared_id_prefix` (round 20) took OUT of the id signal, back in through the
# body. Under that reading the flagged bundle delivers what the unflagged one
# delivers, on 16 of 16 rows.
#
# These cases pin the RULE, never the implementation: every one of them calls
# the entry points WITHOUT the parameter and reads what came back. None of them
# asks a signature what its default is, because a default is a behaviour and a
# signature is a spelling of it.
#
# The two known-negatives above are now on the DEFAULT path rather than behind
# a parameter, which is why they are restated here against it.


def _default_texts(root: Path) -> dict[str, str]:
    """`searchable_text` with NO parameter, keyed by concept id."""
    concepts = [
        okf_consume.read_concept(
            root / f"{concept_id}.md", bundle_root=root, root_bundle_id="link-fixture"
        )
        for concept_id in okf_consume.enumerate_concepts(root)
    ]
    return dict(zip([c.concept_id for c in concepts], okf_consume.searchable_text(concepts)))


def _unflagged(root: Path) -> Path:
    """The same three concepts as `_bundle`, built as the door leaves them
    WITHOUT `--shell-parent`: the shell's body is its heading alone.

    This is Z. `_bundle` is the flagged build, and reading it with the default
    is Y. K3-23's Y = Z control is the one row that makes rank-versus-budget a
    measurement rather than an assumption, so it is restated here in miniature,
    deterministic, and without a corpus.
    """
    _bundle(root)
    (root / "r761" / "skall.md").write_text(
        _FRONTMATTER.format(title="33.212 Boltetype B", digest="1" * 64)
        + "## 33.212 Boltetype B\n",
        encoding="utf-8",
    )
    return root


def _delivered(payload: dict[str, object]) -> list[str]:
    return [str(excerpt["concept_id"]) for excerpt in payload["excerpts"]]  # type: ignore[index,union-attr]


def _spent(payload: dict[str, object]) -> int:
    return int(payload["budget"]["spent"])  # type: ignore[index,call-overload]


def test_the_default_reading_takes_the_doors_line_out_of_the_signal(tmp_path: Path) -> None:
    """`searchable_text` called with NO parameter: the door's line is gone."""
    root = _bundle(tmp_path / "bundle")
    texts = _default_texts(root)
    assert DOOR_LINE not in texts["r761/skall"]


def test_the_default_reading_scores_the_shell_at_zero(tmp_path: Path) -> None:
    """`concept_scores` called with NO parameter: the shell's only hit was the
    line, so its own lexical overlap is 0 and the cut withholds it as a guess."""
    root = _bundle(tmp_path / "bundle")
    concepts = [
        okf_consume.read_concept(
            root / f"{concept_id}.md", bundle_root=root, root_bundle_id="link-fixture"
        )
        for concept_id in okf_consume.enumerate_concepts(root)
    ]
    ranked = okf_consume.concept_scores(
        concepts, QUESTION, okf_consume.document_scores(root, QUESTION)
    )
    scored = {concept.concept_id: lexical for concept, _, lexical in ranked}
    assert scored["r761/skall"] == 0


def test_the_default_payload_reads_the_body_without_the_line(tmp_path: Path) -> None:
    """`build_payload` called with NO parameter equals the explicit `False`."""
    root = _bundle(tmp_path / "bundle")
    implicit = okf_consume.serialise(okf_consume.build_payload(root, question=QUESTION))
    explicit = okf_consume.serialise(
        okf_consume.build_payload(root, question=QUESTION, link_in_signal=False)
    )
    assert implicit == explicit


def test_the_named_default_is_the_one_the_entry_points_read(tmp_path: Path) -> None:
    """The constant this module declares IS the behaviour, not a label beside it.

    Imported from the module that OWNS it -- inside the test, so the red falls
    on the rule and not on collection -- and then spent: a payload built with
    the constant's value must be the payload built with no parameter at all.
    """
    from llm_ingestion_okf.consume import DEFAULT_LINK_IN_SIGNAL

    assert DEFAULT_LINK_IN_SIGNAL is False
    root = _bundle(tmp_path / "bundle")
    implicit = okf_consume.serialise(okf_consume.build_payload(root, question=QUESTION))
    named = okf_consume.serialise(
        okf_consume.build_payload(root, question=QUESTION, link_in_signal=DEFAULT_LINK_IN_SIGNAL)
    )
    assert implicit == named


def test_the_old_reading_is_still_reachable_and_still_does_the_old_thing(
    tmp_path: Path,
) -> None:
    """The default moves; the possibility does not disappear.

    A caller asking for today's reading explicitly gets today's reading -- the
    shell still scores on the line, and the payload is a DIFFERENT one from the
    default's. Both halves, because either alone would pass on a no-op.
    """
    root = _bundle(tmp_path / "bundle")
    assert _lexical(root, link_in_signal=True)["r761/skall"] == 1
    default = okf_consume.serialise(okf_consume.build_payload(root, question=QUESTION))
    old = okf_consume.serialise(
        okf_consume.build_payload(root, question=QUESTION, link_in_signal=True)
    )
    assert default != old


def test_the_flagged_bundle_read_by_default_delivers_what_the_unflagged_one_does(
    tmp_path: Path,
) -> None:
    """Y = Z, in miniature: same list, same ORDER, same `spent`.

    The flagged build read with the default (Y) against the unflagged build read
    with the default (Z). `spent` can be equal here for one reason and it is the
    same reason it was equal on R761: under this reading the shell has no
    lexical hit at all, so it is never delivered, and every concept that IS
    delivered holds bytes the door never touched.
    """
    flagged = okf_consume.build_payload(_bundle(tmp_path / "flagged"), question=QUESTION)
    unflagged = okf_consume.build_payload(_unflagged(tmp_path / "unflagged"), question=QUESTION)
    assert _delivered(flagged) == _delivered(unflagged)
    assert _spent(flagged) == _spent(unflagged)


def test_a_human_line_with_the_same_two_words_survives_the_default_reading(
    tmp_path: Path,
) -> None:
    """Known-negative 1, restated against the default path."""
    root = _bundle(tmp_path / "bundle")
    texts = _default_texts(root)
    assert DOOR_LINE not in texts["r761/skall"]
    assert "Enclosing section: se kapittelet om sikringsbolter." in texts["r761/menneske"]


def test_the_doors_form_anywhere_but_last_survives_the_default_reading(
    tmp_path: Path,
) -> None:
    """Known-negative 2, restated against the default path."""
    root = _bundle(tmp_path / "bundle")
    texts = _default_texts(root)
    assert DOOR_LINE not in texts["r761/skall"]
    assert DOOR_LINE in texts["r761/midt"]
    assert "Denne teksten staar under lenka." in texts["r761/midt"]


def test_the_two_readings_differ_in_rank_and_never_in_an_excerpts_bytes(
    tmp_path: Path,
) -> None:
    """The line stays in the EXCERPT under both readings.

    This is the whole difference between a ranking change and a form change,
    and it is why the two SKILL.md passages describing the line in the excerpt
    need no edit: a concept delivered by both readings carries identical bytes,
    and only the delivered set and its order can move.
    """
    root = _bundle(tmp_path / "bundle")
    default = okf_consume.build_payload(root, question=QUESTION)
    old = okf_consume.build_payload(root, question=QUESTION, link_in_signal=True)
    assert _delivered(default) != _delivered(old)
    by_id_old = {
        str(e["concept_id"]): str(e["text"])  # type: ignore[index]
        for e in old["excerpts"]  # type: ignore[union-attr]
    }
    for excerpt in default["excerpts"]:  # type: ignore[union-attr]
        concept_id = str(excerpt["concept_id"])  # type: ignore[index]
        if concept_id in by_id_old:
            assert str(excerpt["text"]) == by_id_old[concept_id]  # type: ignore[index]


def test_a_bundle_carrying_no_link_is_byte_identical_under_both_readings(
    tmp_path: Path,
) -> None:
    """Section 4A's exposure gate, in miniature and in the suite.

    KNOWN-POSITIVE: on a bundle where NO body ends in the door's form -- which
    is every bundle anyone ships today, 0 of 5 -- moving the default moves not
    one byte. It is the test that would go red if `body_without_link_line` ever
    became eager.
    """
    root = _unflagged(tmp_path / "bundle")
    default = okf_consume.serialise(okf_consume.build_payload(root, question=QUESTION))
    old = okf_consume.serialise(
        okf_consume.build_payload(root, question=QUESTION, link_in_signal=True)
    )
    assert default == old