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. It is not a flag and
not a default; K3-23's measurement decides whether it becomes either.

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_byte_identical_to_the_instrument_off(tmp_path: Path) -> None:
    """The instrument ships OFF: no default moves until K3-23's numbers say so."""
    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=True)
    )
    assert implicit == explicit