portfolio-optimiser/tests/test_proposal_review_loop_loadbearing.py

"""MAJOR-2 — a human must be able to answer the proposal that is ON THE TABLE, and the answer
must be USED.

Measured before this door existed (``docs/2026-09-02-misjonsreview-v2.md`` § 3, re-measured at
HEAD ``da5f10f``): ``grep -n "prior_" generate.py`` finds exactly ONE seam — ``prior_rejection``,
the MACHINE's own falsification fed back inside the same run — and the only human seam in the
loop is ``plan_reviewer``, which fires BEFORE any hypothesis exists. A human's verdict lands in
the NEXT run (Step 7's inbox). So "improved proposals given feedback" was, for a person, a
two-run loop with days between it.

**The gate is the SECOND half of that phrase.** A door that renders the candidate, reads a line
and discards it passes "the expert was asked" and fails the målbilde — this repo's vacuous-gate
class, fifteen times over. Every arm here is therefore built so that an **always-approve
reviewer is RED**: the discriminator is that a ``revise`` reaches the NEXT generation attempt's
prompt VERBATIM, that the proposer answers differently because of it, and that the run carries
the validator's ruling on THAT attempt (D6).

Three things the door must NOT do, gated as hard as the things it must: ``approve`` mints no
``Verdict`` (F2 stands); a ``revise`` never writes ``provenance.validator_decision`` and never
touches the checker gate (the two falsifiers stay unblended — the human is a third voice that
gates nothing except asking for one more attempt); and a run with NO reviewer is byte-identical
to today, golden transcript included.
"""

from __future__ import annotations

import json
from pathlib import Path

import pytest
from spikes._harness import message_texts

from portfolio_optimiser import proposal_review as pr
from portfolio_optimiser.generate import _build_messages
from portfolio_optimiser.ir import AffectedItem, SavingsProposal
from portfolio_optimiser.reference_domain import load_reference_projects
from portfolio_optimiser.validator import Rejection, ValidatedProposal

_REPO = Path(__file__).resolve().parents[1]
_BUNDLE_DIR = _REPO / "shared" / "examples" / "bygg-energi-mikro"
_PID = "BYGG-KONTOR-NORD"
_RUN_ID = "proposal-review-door"

#: A string that can reach a generation prompt ONLY by travelling through the expert's feedback:
#: asserted absent from every file of the fixture bundle and from the base prompt (Step 2), so a
#: prompt that carries it can have got it from exactly one place.
_FEEDBACK_SENTINEL = "PROPOSAL-REVIEW-SENTINEL-9c41ae"

#: The shape of the defect BLOCKER-1 measured, asserted NEGATIVELY: any object rendered by its
#: default repr onto a surface a human reads. Stronger than a positive sentinel alone, which a
#: renderer that prints nothing at all would also satisfy.
_REPR_LEAK = " object at 0x"


def _proposal(*, amount: float = 30000.0, measure: str = "LED-retrofit") -> SavingsProposal:
    return SavingsProposal(
        project_id=_PID,
        measure=measure,
        affected_items=[AffectedItem(code="ENERGI-TOTAL-EL", quantity=300000.0, unit_cost=1.0)],
        claimed_saving_nok=amount,
    )


def _validated(*, amount: float = 30000.0, p50: float = 42.0) -> ValidatedProposal:
    return ValidatedProposal(
        proposal=_proposal(amount=amount),
        p10=p50 - 1.0,
        p50=p50,
        p90=p50 + 1.0,
        nominal_feasible=p50 + 2.0,
    )


def _review(
    *,
    approach_id: str | None = None,
    attempt: int = 0,
    decision: str = "approve",
    feedback: str = "",
    honoured: bool = True,
    p50: float = 42.0,
) -> pr.ProposalReview:
    return pr.ProposalReview(
        approach_id=approach_id,
        attempt=attempt,
        decision=decision,  # type: ignore[arg-type]
        feedback=feedback,
        honoured=honoured,
        proposal=_validated(p50=p50),
    )


# ---------------------------------------------------------------------------------------------
# Group A0 (Step 1) — the types, the error's CLASS, and the two renderers.
# ---------------------------------------------------------------------------------------------


def test_a_revision_must_say_what_to_revise() -> None:
    """Detach point: ``ProposalReviewDecision.revise`` accepting an empty string. A bare
    ``revise`` is not a decision — it is a line the door must ask again for. The type refuses it
    at construction so no surface can invent the distinction for itself."""
    with pytest.raises(ValueError):
        pr.ProposalReviewDecision.revise("")
    with pytest.raises(ValueError):
        pr.ProposalReviewDecision.revise("   ")
    assert pr.ProposalReviewDecision.revise("do X").feedback == "do X"
    assert pr.ProposalReviewDecision.approve().feedback is None


def test_the_input_error_is_a_runtime_error_and_never_a_value_error() -> None:
    """Detach point: making ``ProposalReviewInputError`` a ``ValueError``. **The class IS the
    channel**, decided by three measurements (brief § Constraints): a ``ValueError`` would land
    on ``run.py``'s refusal tuple and print ``run refused:`` for a run whose argv was fine and
    which had already spent tokens; and it would sit ONE frame from ``_fetch_parsed``'s
    ``except (ValidationError, ValueError, TypeError)`` catch-all, where a human-input error
    would be appended to ``parse_failures`` and the model re-called until the ledger fired.
    Both halves are asserted, because ``issubclass(X, RuntimeError)`` alone stays green on a
    class that inherits from both."""
    assert issubclass(pr.ProposalReviewInputError, RuntimeError)
    assert not issubclass(pr.ProposalReviewInputError, ValueError)


def test_the_notice_is_none_exactly_when_no_reviewer_was_offered() -> None:
    """Detach point: a renderer that always returns its line. The ``announce`` rule: a run that
    offered no reviewer has nothing to say, and an empty row would read as a dropped line."""
    assert pr.proposal_review_notice((), offered=False) is None
    assert pr.proposal_review_notice((_review(),), offered=False) is None
    assert pr.proposal_review_notice((), offered=True) is not None


def test_zero_reviews_with_a_reviewer_offered_says_so_in_words() -> None:
    """Detach point: returning ``None`` on zero reviews with a reviewer present (M33).

    A DELIBERATE departure from the announce rule's zero-is-silence half, and the reason is the
    operator: someone who passed ``--proposal-review`` and sees nothing cannot tell "no candidate
    was ever validated, so nobody was asked" from "the door hung". The departure is stated in the
    invariant row rather than left as an inconsistency."""
    line = pr.proposal_review_notice((), offered=True)
    assert line == "  proposal review offered, never consulted (no candidate validated)"


def test_the_notice_counts_answers_candidates_and_the_unhonoured_ones() -> None:
    """Detach point: dropping the un-honoured tail, or counting entries instead of candidates.

    An un-honoured revise (no attempt left to buy) is a FACT the operator must be able to read:
    the expert asked for a change that the run could not make."""
    reviews = (
        _review(approach_id="a1", attempt=0, decision="revise", feedback="F", honoured=True),
        _review(approach_id="a1", attempt=1, decision="approve"),
        _review(approach_id="a2", attempt=0, decision="revise", feedback="G", honoured=False),
    )
    assert pr.proposal_review_notice(reviews, offered=True) == (
        "  proposal review: 3 answer(s) across 2 candidate(s) — 1 approve, 2 revise "
        "(1 not honoured)"
    )
    honoured_only = (
        _review(approach_id="a1", attempt=0, decision="revise", feedback="F", honoured=True),
        _review(approach_id="a1", attempt=1, decision="approve"),
    )
    assert pr.proposal_review_notice(honoured_only, offered=True) == (
        "  proposal review: 2 answer(s) across 1 candidate(s) — 1 approve, 1 revise"
    )


def test_the_payload_carries_every_field_and_takes_its_key_from_the_injected_function() -> None:
    """Detach point: dropping ``verdict_key`` (M28), or deriving it inside the module.

    ``verdicts.verdict_key`` takes ``ProposalFeatures`` and the only derivation from a
    ``SavingsProposal`` is ``run._features_of`` — but ``verdicts.py`` imports MAF and ``run`` is
    a cycle from here, so the key function is INJECTED and ``_features_of`` stays the single
    home (kø-(p)). The arm asserts the injected callable is handed the REVIEWED proposal, not a
    re-derived one."""
    seen: list[SavingsProposal] = []

    def key_of(proposal: SavingsProposal) -> str:
        seen.append(proposal)
        return f"key-{len(seen)}"

    reviews = (
        _review(approach_id="a1", attempt=0, decision="revise", feedback="F", honoured=False),
        _review(approach_id=None, attempt=1, decision="approve", p50=99.5),
    )
    payload = pr.proposal_reviews_payload(reviews, key_of=key_of)

    assert list(payload) == ["reviews"]
    assert payload["reviews"] == [
        {
            "approach_id": "a1",
            "attempt": 0,
            "decision": "revise",
            "feedback": "F",
            "honoured": False,
            "verdict_key": "key-1",
            "p50": 42.0,
        },
        {
            "approach_id": None,
            "attempt": 1,
            "decision": "approve",
            "feedback": "",
            "honoured": True,
            "verdict_key": "key-2",
            "p50": 99.5,
        },
    ]
    assert seen == [reviews[0].proposal.proposal, reviews[1].proposal.proposal]
    # The payload is a PLAIN mapping: ``outbox`` stays MAF-free and byte-deterministic.
    assert json.loads(json.dumps(payload)) == payload


# ---------------------------------------------------------------------------------------------
# Group A1 (Step 2) — ``prior_feedback``: the third composable block of the hypothesis prompt.
# ---------------------------------------------------------------------------------------------


@pytest.fixture(scope="module")
def project():
    return load_reference_projects()[0]  # FV42-GSV-E1


def test_prior_feedback_none_keeps_the_base_prompt_byte_identical(project) -> None:
    """CONTROL: the new block is INERT when nobody reviewed. A test that can only go green
    proves nothing, and this is the half that keeps every existing run, golden and nav-fixture
    untouched — the contract ``prior_rejection`` and ``approach`` already state."""
    base = message_texts(_build_messages(project, "ctx"))[0]
    assert base == message_texts(_build_messages(project, "ctx", prior_feedback=None))[0]
    assert _FEEDBACK_SENTINEL not in base


def test_the_experts_words_reach_the_next_prompt_verbatim(project) -> None:
    """Detach point: dropping the ``prior_feedback`` block (M3 — print-and-discard).

    VERBATIM and only the text: never the previous proposal JSON. That is the ``prior_rejection``
    rule, and it is the same reason — the model must address what the human said, not parrot the
    candidate they were unhappy with."""
    text = message_texts(
        _build_messages(
            project, "ctx", prior_feedback=f"Use 150000, not 200000. {_FEEDBACK_SENTINEL}"
        )
    )[0]
    assert _FEEDBACK_SENTINEL in text
    assert "asked for a revision" in text
    assert "Use 150000, not 200000." in text


def test_a_rejection_and_a_standing_feedback_compose_in_order(project) -> None:
    """The two blocks compose, and the ORDER is fixed: base -> approach head -> rejection ->
    feedback.

    This is the shape T6 measures end to end: a revise whose bought attempt the validator then
    rejects leaves the attempt after it carrying BOTH — the human's instruction stands until the
    human next answers, the machine's reason is per-attempt (only the most recent, as today)."""
    rejection = Rejection(proposal=_proposal(), reason="claimed saving 270000 exceeds P90 121057")
    text = message_texts(
        _build_messages(
            project, "ctx", prior_rejection=rejection, prior_feedback=_FEEDBACK_SENTINEL
        )
    )[0]
    assert text.count(rejection.reason) == 1
    assert text.count(_FEEDBACK_SENTINEL) == 1
    assert text.index("REJECTED by the deterministic validator") < text.index(_FEEDBACK_SENTINEL)


def test_the_feedback_sentinel_cannot_arrive_from_the_knowledge_base() -> None:
    """The known-positive control on every sentinel arm in this file: the marker exists NOWHERE
    in the fixture bundle, so a prompt that carries it can only have got it through the expert's
    feedback block. Paired with an assertion that the scan actually reads the files — a scan that
    silently finds nothing makes a gate that can only go green."""
    texts = [
        path.read_text(encoding="utf-8")
        for path in sorted(_BUNDLE_DIR.rglob("*"))
        if path.is_file()
    ]
    assert texts, "the fixture bundle must exist for this control to mean anything"
    assert any("ENERGI-TOTAL-EL" in text for text in texts)  # the scan CAN find a known string
    assert not any(_FEEDBACK_SENTINEL in text for text in texts)