portfolio-optimiser/tests/test_unnamed_excerpt_observation_loadbearing.py

"""Load-bearing gate for order 20260910T051343Z (P10): a delivered excerpt nobody named is NAMED.

**The measured hole.** P9 ran ``okf check`` (0.7.0, 15 rules) over this repository's payloads and
got rc 0 on ``payload-n100.json`` and rc 1 on BOTH K2 payloads -- **20 findings, every one of them
``excerpt_unnamed``**: "an excerpt a reader cannot name is one an answer cannot cite, whatever its
rank (SS 8)". That diagnosis is right and it is not a solution: on po's side the same absence is
SILENT. ``_excerpt_header`` appends the ``title:`` field only ``if excerpt.title is not None`` and
says nothing otherwise, so a payload whose every excerpt is unnamed renders exactly like one whose
producer simply had nothing to add, and no surface of a run carries the difference.

**F1 (reporting), not F2 (refusing) -- and the price of F2 is a NUMBER.** Making ``title``
required and refusing in ``check_payload_shape`` would reverse a written decision:
``PrepassExcerpt``'s docstring states that every new field defaults to ``None`` because "a
required field would refuse every payload written before today". Measured against that claim on
2026-09-10: of the **20** payload files in this repository, **10 carry a ``title`` on every
excerpt and 10 carry it on none** -- and among the ten F2 would refuse is
``tests/fixtures/prepass/bygg-energi-mikro-fixture.payload.json`` (4 excerpts, 0 titled), the ONE
git-tracked payload fixture, which drives every other prepass suite. F2 would therefore require
rewriting a tracked fixture to make its own rule green. F1 refuses nothing and observes instead.

**The observation is an ABSENCE, mirroring okf's rule exactly, and it is not repair.** Only a
missing ``title`` is reported. An excerpt whose producer wrote ``title: ""`` HAS been named, badly
-- that is the producer's fact to state and ours to render, not ours to reclassify; the header
already shows it as ``title: `` where an absent one shows nothing at all.

**The tuple DEFAULTS**, the ``skipped_links`` half of the rule rather than
``cost_baseline_anchored``'s: an empty trace here is an honest POSITIVE statement -- "every
delivered excerpt was named" -- whereas a required boolean would have to assert something about an
event and both defaults would sometimes lie.
"""

from __future__ import annotations

import json
from pathlib import Path
from typing import Any

from portfolio_optimiser import prepass

FIXTURE = Path(__file__).parent / "fixtures" / "prepass" / "bygg-energi-mikro-fixture.payload.json"


def _raw() -> dict[str, Any]:
    return json.loads(FIXTURE.read_text(encoding="utf-8"))


def _titled_everywhere() -> dict[str, Any]:
    """The known-positive: every delivered excerpt carries a ``title``."""
    raw = _raw()
    for index, excerpt in enumerate(raw["excerpts"]):
        excerpt["title"] = f"Named concept {index}"
    return raw


# --- the observation itself ---------------------------------------------------------------------


def test_an_excerpt_without_a_title_is_named() -> None:
    """The delivered excerpts that carry no ``title`` come back BY CONCEPT ID, in payload order.

    Not a count: "3 of 4 excerpts are unnamed" is not actionable against a producer, and
    "these three concepts are" is -- ``BudgetExceeded``'s ko-(y) rule one level down.
    """
    raw = _raw()
    ids = [excerpt["concept_id"] for excerpt in raw["excerpts"]]
    assert len(ids) >= 3, "the fixture must carry enough excerpts to prove ORDER, not just presence"
    raw["excerpts"][1]["title"] = "Named concept 1"
    payload = prepass.PrepassPayload.model_validate(raw)

    observed = prepass.unnamed_excerpts(payload)

    assert observed == tuple(name for index, name in enumerate(ids) if index != 1)


def test_a_payload_whose_every_excerpt_is_named_observes_nothing() -> None:
    """The KNOWN-POSITIVE control. Without it a rule that always fires would pass the arm above."""
    payload = prepass.PrepassPayload.model_validate(_titled_everywhere())
    assert prepass.unnamed_excerpts(payload) == ()


def test_an_empty_title_is_a_name_the_producer_chose_not_an_absence() -> None:
    """Validation, NEVER repair: ``title: ""`` is a producer's own naming and is not reclassified.

    okf's rule is "carries no ``title``", and mirroring it exactly is what keeps this observation
    from becoming a second, divergent opinion about what a name is.
    """
    raw = _titled_everywhere()
    raw["excerpts"][0]["title"] = ""
    payload = prepass.PrepassPayload.model_validate(raw)
    assert prepass.unnamed_excerpts(payload) == ()


# --- it reaches the surfaces the declaration already reaches -------------------------------------


def test_the_observation_reaches_the_declaration() -> None:
    payload = prepass.PrepassPayload.model_validate(_raw())
    declaration = prepass.declaration_of(payload, rest_reachable=False)
    assert declaration.unnamed_excerpts == tuple(excerpt.concept_id for excerpt in payload.excerpts)


def test_a_fully_named_payload_declares_an_empty_trace() -> None:
    payload = prepass.PrepassPayload.model_validate(_titled_everywhere())
    assert prepass.declaration_of(payload, rest_reachable=True).unnamed_excerpts == ()


def test_the_observation_reaches_the_artefact() -> None:
    """``{run_id}-prepass.json`` is where a reader looks after the run; an observation that stopped
    at the dataclass would be invisible exactly where the denominators are read."""
    payload = prepass.PrepassPayload.model_validate(_raw())
    body = prepass.declaration_payload(prepass.declaration_of(payload, rest_reachable=False))
    assert body["unnamed_excerpts"] == [excerpt.concept_id for excerpt in payload.excerpts]


# --- F1's promise: nothing that used to load stops loading ---------------------------------------


def test_no_existing_payload_is_refused() -> None:
    """The tracked fixture carries a ``title`` on NONE of its excerpts and must still load and
    still pass the shape check -- this is the whole difference between F1 and F2."""
    payload = prepass.load_prepass_payload(str(FIXTURE))
    assert all(excerpt.title is None for excerpt in payload.excerpts)
    prepass.check_payload_shape(payload)