portfolio-optimiser/tests/test_okf_version_guard.py

"""P13 okf/guard version-guard — a TEST-TIME tripwire on the two Door A pins, + the install half.

Door A depends on ``llm-ingestion-okf``'s PUBLIC surface (27 names across five modules, imported by
``ingest.py``/``ingest_mcp.py``) and, through it, on ``llm-ingestion-guard``'s ``okf`` adapter.
Neither is pinned by a version RANGE in ``pyproject.toml`` — both are git tag pins — so the tag IS
the pin and EQUALITY is the right predicate here, not a floor: there is no declared range for a
newer release to sit inside, so any movement is a decision, never maintenance. That is the one shape
difference from ``test_maf_version_guard``, whose ``pyproject`` really does declare
``>=1.18.0,<2``.

A grep on ``pyproject.toml`` alone would be blind to an environment that drifted from the lock (a
stale ``.venv``, a shadowing tool install), and a version assert alone would be blind to a lock that
drifted from the declared pin. This guard is both halves.

**What the pinned pair costs, and why it is named in the refusal.** P13 measured the lift and
REFUSED it; P13b closed the blocker and landed it. okf >=0.8.5 emits the V1 provenance stamp
``generated: { by: process:okf-ingest, at: <ingested_at> }`` where 0.3.2 emitted ``generated: true``,
and ``okf._carries_complete_ingest_stamp`` read the new form as NOT a stamp — the
``write_concept_file`` forgery refusal went inert on exactly the output it guards against, with the
whole fail-closed suite green. ``_claims_ingest_ownership`` now recognises BOTH spellings. Any
further lift must re-measure that predicate against what the new release actually writes, because
nothing in the suite would go red if a third spelling appeared. The refusal messages below name it,
because a pin whose reason lives only in prose is a pin the next session lifts without
re-measuring. Full numbers: ``docs/2026-09-12-p13-okf-pin-r761.md`` and ``…-p13b-okf-bump.md``.
"""

from __future__ import annotations

import importlib.metadata
from pathlib import Path

import pytest

_OKF_DIST = "llm-ingestion-okf"
_GUARD_DIST = "llm-ingestion-guard"

#: The measured-green pins. ONE place each; the ``pyproject`` asserts DERIVE their expected strings
#: from these (the kø-(p) rule) — two literals for one fact drift, and a drifted pin is a guard that
#: stops guarding without a local diff.
_OKF_PINNED = "0.8.5"
_GUARD_PINNED = "1.4.0"

_OKF_LIFT_COST = (
    "Before lifting, re-measure what this release EMITS as the §7 ownership stamp and check "
    "okf._claims_ingest_ownership still recognises it. 0.3.2 wrote 'generated: true'; 0.8.5 writes "
    "the V1 flow mapping 'generated: { by: process:okf-ingest, at: ... }', and the detector that "
    "knew only the boolean left write_concept_file's forgery refusal INERT with the whole "
    "fail-closed suite green (P13 § 2c'). A third spelling would do the same. Then expect the four "
    "examples/ingest-golden-* byte goldens (seven concept files) and conftest."
    "expected_generated_stamp to move with it. See docs/2026-09-12-p13b-okf-bump.md."
)

_GUARD_LIFT_COST = (
    "The guard's 1.0.0 freeze covers the exported SURFACE only: severities, thresholds and the "
    "dispositions they produce are explicitly calibration and move within 1.x. "
    "ingest._ACCEPTED_DISPOSITION reads 'warn' as the lowest tier a clean concept scores — "
    "re-measure it before lifting. Note also that okf >=0.8.5 pins this library itself via "
    "[tool.uv.sources] tag = 'v1.4.0', so a consumer cannot choose a lower 1.x, and must spell its "
    "own pin with tag= rather than rev= or uv refuses the resolution as conflicting URLs — which "
    "is why pyproject.toml spells this one tag= and the okf one rev=."
)


def assert_pinned_okf_version(version_str: str) -> None:
    """Raise ``ValueError`` unless ``version_str`` is the pinned okf tag, naming the measured cost
    of the lift. Pure string compare — no import side effects, so a version can be passed directly
    (the RED-proof) without touching the real install."""
    if version_str != _OKF_PINNED:
        raise ValueError(
            f"{_OKF_DIST} {version_str} is not the pinned {_OKF_PINNED}. {_OKF_LIFT_COST}"
        )


def assert_pinned_guard_version(version_str: str) -> None:
    """Raise ``ValueError`` unless ``version_str`` is the pinned guard tag, naming the premise the
    surface freeze does NOT cover."""
    if version_str != _GUARD_PINNED:
        raise ValueError(
            f"{_GUARD_DIST} {version_str} is not the pinned {_GUARD_PINNED}. {_GUARD_LIFT_COST}"
        )


def test_installed_okf_version_is_the_pinned_one() -> None:
    """The control for both refusal arms below: the REAL installed distribution passes, read from
    ``importlib.metadata`` — what is in the environment, not what the lock says should be."""
    assert_pinned_okf_version(importlib.metadata.version(_OKF_DIST))


def test_installed_guard_version_is_the_pinned_one() -> None:
    """Same control, for the guard."""
    assert_pinned_guard_version(importlib.metadata.version(_GUARD_DIST))


def test_okf_guard_trips_on_the_measured_lift_and_on_its_neighbours() -> None:
    """``0.3.2`` is the pin P13b lifted FROM, so a revert cannot pass silently; ``0.4.0`` is where
    the guard first became a hard runtime dependency of okf; ``0.8.4``/``0.8.6`` bracket the pinned
    one, so a neighbouring tag cannot slip in under a range this pin does not have."""
    for other in ("0.3.2", "0.4.0", "0.7.0", "0.8.4", "0.8.6", "0.9.0", "1.0.0"):
        with pytest.raises(ValueError, match="write_concept_file"):
            assert_pinned_okf_version(other)


def test_guard_version_guard_trips_on_the_lift_okf_would_force() -> None:
    """``0.3.4`` is the pin P13b lifted FROM; ``1.2.0`` is the lowest 1.x satisfying okf's declared
    ``>=1.2,<2.0`` and is NOT choosable, because okf pins this library itself at ``v1.4.0``;
    ``2.0.0`` is where the surface freeze ends."""
    for other in ("0.3.4", "1.2.0", "1.3.0", "2.0.0"):
        with pytest.raises(ValueError, match="calibration"):
            assert_pinned_guard_version(other)


def test_pyproject_pins_both_tags() -> None:
    """The install-time half. The expected strings are DERIVED from the pins above so the two halves
    cannot drift apart."""
    pyproject = (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text(encoding="utf-8")
    assert f'llm-ingestion-okf.git", rev = "v{_OKF_PINNED}" }}' in pyproject
    # `tag =`, not `rev =`: measured, not stylistic. See _GUARD_LIFT_COST.
    assert f'llm-ingestion-pipeline-security.git", tag = "v{_GUARD_PINNED}" }}' in pyproject