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
from pathlib import Path

from portfolio_optimiser import okf, 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,
    )