portfolio-optimiser/tests/test_falsification_verdict_loadbearing.py

"""The falsification-verdict seam — load-bearing gates for reading OKF provenance.

This module opens with the ONE thing that has to be captured before any decoder exists: the
bytes today's ``bundle_context`` renders from a **block-form** provenance bundle. Later steps
add a decoder that reads ``verified``/``sources`` in that form; this gate is what proves the
decoder did not move the read-context on its way in.

The comparison is **byte-for-byte**, with no trailing-whitespace normalisation. The commons
nav-goldens normalise because commons owns their line endings and this repo consumes them
through a pull-only subtree; ``tests/golden/block-form-provenance/`` is repo-owned, so the
stricter comparison is available and is what the criterion asks for.

The resolver below is LOCAL on purpose. ``tests/test_okf.py::_nav_golden`` hard-codes
``shared/examples/`` (``test_okf.py:51``) and lives in a module this work must not touch, so
reusing it would mean editing a frozen module to reach a repo-owned fixture.
"""

from __future__ import annotations

import shutil
import tempfile
from pathlib import Path

import pytest

from portfolio_optimiser import okf, tools, verdicts

_GOLDEN_DIR = Path(__file__).resolve().parents[1] / "tests" / "golden" / "block-form-provenance"


def _block_form_golden() -> tuple[str, str]:
    """The repo-owned block-form case: ``(bundle_dir, expected_read_context)``."""
    return (
        str(_GOLDEN_DIR / "bundle"),
        (_GOLDEN_DIR / "expected-read-context.md").read_text(encoding="utf-8"),
    )


def test_block_form_bundle_renders_the_captured_bytes() -> None:
    """Navigation is TOLERANT of block-form provenance, and these are the bytes it produces.

    Two claims in one arm, and both are load-bearing. First, ``navigate_bundle`` reaches every
    file and skips nothing — a block ``verified:`` sequence is ordinary frontmatter to a
    line-oriented parser, so it must not break navigation, and ``skipped`` being empty is the
    positive statement that no link was silently passed over. Second, the rendered read-context
    is byte-identical to the committed fasit. The fasit was generated by the code that predates
    any decoder work: if it were regenerated afterwards, the comparison would prove an
    implementation identical to itself and nothing else.
    """
    bundle_dir, expected = _block_form_golden()
    bundle = okf.navigate_bundle(bundle_dir)

    assert bundle.skipped == (), (
        f"navigation skipped a link it should have followed: {bundle.skipped}"
    )
    assert [f.name for f in bundle.files] == ["index.md", "attested.md", "multi-verified.md"]

    assert okf.bundle_context(bundle) == expected


# --- Step 7: the falsification verdict, with the third state carrying its reason ---------------

_ENERGI_BUNDLE = Path(__file__).resolve().parents[1] / "shared" / "examples" / "bygg-energi-mikro"


def _present_document(tmp_path: Path) -> Path:
    """A REAL flow-form document, produced by our own writer — never a mock.

    All three arms below read committed or freshly-written files, because the property under test
    is what the reader does with bytes on disk, and a stubbed reader would test the stub.
    """
    dst = tmp_path / "bundle"
    shutil.copytree(_ENERGI_BUNDLE, dst)
    return verdicts.promote_verdict(
        str(dst),
        verdicts.Verdict(
            id="EVIDENCE-PRESENT",
            proposal_features=verdicts.bundle_candidate_features(str(dst)),
            decision="approved",
            rationale="godkjent",
        ),
        approver="process:fixture-check",
        experiment="exp-B",
        timestamp="2026-06-30T09:00:00Z",
    )


def test_a_flow_form_document_is_present_and_tiered(tmp_path: Path) -> None:
    """CONTROL — without it, every arm below is satisfied by a reader that always says "absent"."""
    evidence = okf.evidence_for(_present_document(tmp_path))
    assert evidence.state == "present"
    assert evidence.tier == "machine-confirmed"
    assert evidence.reason is None, (
        "a present state has no reason to carry, and must not invent one"
    )
    assert evidence.items_seen == 1


def test_a_document_without_the_key_is_absent_and_carries_no_tier() -> None:
    """``absent`` is what a document that never claimed verification says — and it is NOT the same
    fact as ``unreadable``."""
    evidence = okf.evidence_for(_GOLDEN_DIR / "bundle" / "index.md")
    assert evidence.state == "absent"
    assert evidence.tier is None
    assert evidence.reason is None
    assert evidence.items_seen == 0


def test_a_block_form_document_is_unreadable_and_says_WHY() -> None:
    """The third state, and the arm asserts the REASON, not merely the state.

    A collapsed ``unreadable`` → ``absent`` is a verdict on missing evidence presented as evidence
    of absence. Asserting only ``state != "present"`` would stay green against exactly that
    collapse, so the reason token is what this arm pins.
    """
    evidence = okf.evidence_for(_GOLDEN_DIR / "bundle" / "attested.md")
    assert evidence.state == "unreadable"
    assert evidence.reason == "block-sequence"
    assert evidence.items_seen == 1


def test_a_two_entry_block_document_yields_NO_tier() -> None:
    """A tier here would be the measured second-entry-wins defect surfacing.

    ``multi-verified.md`` carries a human sign-off FIRST and a process entry SECOND. A reader that
    limped past the block form and kept the last entry it saw would report ``machine-confirmed``
    for a concept a human signed — downgrading the tier with nothing failing. The honest answer to
    an unreadable value is no tier at all.
    """
    evidence = okf.evidence_for(_GOLDEN_DIR / "bundle" / "multi-verified.md")
    assert evidence.state == "unreadable"
    assert evidence.tier is None
    assert evidence.items_seen == 2


def test_evidence_notice_is_None_when_there_is_nothing_to_say(tmp_path: Path) -> None:
    """Omission, never an empty row — the ``cost_baseline_notice`` precedent."""
    assert okf.evidence_notice(okf.evidence_for(_present_document(tmp_path))) is None


def test_evidence_notice_prints_the_reason_TOKEN_itself() -> None:
    """No second display vocabulary. A prose translation here would be free to drift from
    ``ProvenanceReason``, and the drifted copy is the one the operator would read."""
    notice = okf.evidence_notice(okf.evidence_for(_GOLDEN_DIR / "bundle" / "attested.md"))
    assert notice is not None
    assert "block-sequence" in notice
    assert "items_seen=1" in notice


# --- Amendment A: the K5 threshold ------------------------------------------------------------


def test_admits_falsification_refuses_a_state_that_is_not_present() -> None:
    """AMENDMENT A, first conjunct — a verdict may not rest on evidence that was never read."""
    assert not okf.admits_falsification(okf.evidence_for(_GOLDEN_DIR / "bundle" / "attested.md"))
    assert not okf.admits_falsification(okf.evidence_for(_GOLDEN_DIR / "bundle" / "index.md"))


def test_admits_falsification_refuses_an_unverified_tier() -> None:
    """AMENDMENT A, second conjunct — its OWN arm, because one arm cannot separate two conjuncts.

    **This state is not reachable through ``evidence_for`` today, and that is measured, not
    assumed:** ``decode_flow_value`` refuses an empty flow sequence, so a ``present`` value always
    carries at least one entry naming an actor, and ``trust_tier`` therefore never answers
    ``unverified`` for it. The conjunct is DEFENSIVE, which is precisely why it needs an arm of its
    own — a single arm over a reachable document would leave it untested, and an untested conjunct
    is one a later simplification deletes without anything going red.
    """
    unverified = okf.FalsificationEvidence(
        file="crafted.md", state="present", tier="unverified", reason=None, entries=(), items_seen=0
    )
    assert not okf.admits_falsification(unverified)


def test_admits_falsification_ADMITS_the_positive_case(tmp_path: Path) -> None:
    """CONTROL — an always-refusing threshold passes both negative arms and is worthless."""
    assert okf.admits_falsification(okf.evidence_for(_present_document(tmp_path)))


def test_a_discounted_concept_reports_the_TRIPLE_not_merely_the_refusal() -> None:
    """AMENDMENT A — "why it was discounted" is the operative fact.

    A dropped concept and a discounted one are different facts, and only the second is honest about
    what was read. Asserting that admission was denied says nothing about which of them happened;
    the triple ``(state, reason, items_seen)`` is what makes the difference legible.
    """
    evidence = okf.evidence_for(_GOLDEN_DIR / "bundle" / "multi-verified.md")
    assert not okf.admits_falsification(evidence)
    assert (evidence.state, evidence.reason, evidence.items_seen) == (
        "unreadable",
        "block-sequence",
        2,
    )


# --- Step 8: the adjudication state, named and never collapsed to absent ------------------------


def _concept(text: str) -> Path:
    path = Path(tempfile.mkdtemp(prefix="okf-adjudication-")) / "c.md"
    path.write_text(text, encoding="utf-8")
    return path


@pytest.mark.parametrize("value", ["proposed", "adjudicated"])
def test_the_two_named_states_are_read_back(value: str) -> None:
    """Hand-written fixtures, to the contract as delivered.

    **Honesty limit, stated:** these are written to the contract, NOT produced by
    ``llm-ingestion-okf``. Integration against the producer's own golden is later work and is not
    claimed here.
    """
    assert okf.adjudication_for(
        _concept(f"---\ntype: concept\nadjudication: {value}\n---\nb\n")
    ) == (value)


def test_a_missing_key_is_unknown_and_NEVER_absent() -> None:
    """The third token is the whole step.

    A concept that does not carry the key means *we did not learn whether this was adjudicated* —
    an older bundle. Collapsing that into "it was not adjudicated" is the same defect as collapsing
    ``unreadable`` into ``absent`` one layer up, and the same defect removed from
    ``RunResult.verdict``.
    """
    assert okf.adjudication_for(_concept("---\ntype: concept\ntitle: x\n---\nb\n")) == "unknown"


@pytest.mark.parametrize("value", ["ratified", "PROPOSED", ""])
def test_a_value_outside_the_vocabulary_is_refused_by_name(value: str) -> None:
    """Validation, never repair. Mapping an unknown value to ``unknown`` would invent the very
    state this contract exists to keep honest — and an EMPTY value is present-but-empty, which is a
    different fact from absent and must not be folded into it either."""
    with pytest.raises(okf.AdjudicationValueError) as excinfo:
        okf.adjudication_for(_concept(f"---\ntype: concept\nadjudication: {value}\n---\nb\n"))
    assert "adjudication" in str(excinfo.value)


def test_the_carrier_hands_the_STATE_to_a_hypothesiser(tmp_path: Path) -> None:
    """THE LOAD-BEARING ARM — the gate is the CARRIER, not the enum.

    An accessor that returns three tokens which nothing propagates is a vocabulary, not a seam. So
    the assertion is on what the tool actually hands back: a payload carrying the state. A carrier
    that returned the concept without its state would leave ``adjudication_for`` correct and the
    hypothesiser none the wiser, which is the exact shape this step exists to close.
    """
    bundle = tmp_path / "bundle"
    bundle.mkdir()
    (bundle / "a.md").write_text(
        "---\ntype: concept\nadjudication: proposed\n---\nbody\n", encoding="utf-8"
    )

    carrier = tools.make_adjudication_tool(str(bundle))
    payload = tools.adjudication_payload(str(bundle), "a.md")

    assert payload["adjudication"] == "proposed"
    assert payload["concept"] == "a.md"
    assert carrier.name == "concept_adjudication_state"


def test_the_carrier_is_a_library_primitive_not_wired_into_the_run(tmp_path: Path) -> None:
    """``run.py`` must not import the carrier: wiring it into the run surface would move the
    byte-pinned demo transcript, and would make the state reachable only by reading a run's output
    rather than by calling a function."""
    run_source = (
        Path(__file__).resolve().parents[1] / "src" / "portfolio_optimiser" / "run.py"
    ).read_text(encoding="utf-8")
    assert "make_adjudication_tool" not in run_source
    assert "adjudication_payload" not in run_source