portfolio-optimiser-claude/tests/test_ingest_stamp_conformance_loadbearing.py

"""Recorded non-conformance: the §7 `generated` stamp, spec V1 vs. the pinned emitter.

commons ratified AND executed V1 (`generated` → the O2 inline mapping) in the ingest spec
this repo consumes unchanged. Our emitter does not implement it: ``materialize()``
delegates to ``llm-ingestion-okf``, pinned at v0.3.2, which still writes the pre-V1 literal
``generated: true``. The golden bundles are that emitter's OUTPUT compared byte-for-byte
(``test_ingest_golden.py``), so the byte form is NOT ours to edit — adopting O2 by hand
would turn the suite RED against the pin rather than conformant. Adoption is gated on an
okf release that emits O2, and the pin move is operator-owned (network + ``pyproject.toml``).

The honesty rule (§1, unwaivable) forbids leaving that silent. After the commons pull the
whole suite stayed green while the shipped spec and the shipped emission disagreed —
green-but-dead, the exact failure mode §11 exists for. This file is the RATCHET that makes
the divergence load-bearing in BOTH directions:

- spec side — RED if §7 stops defining the O2 mapping (commons reverts or amends it).
- emitter side — RED the moment a materialize() run stops emitting the pre-V1 literal, i.e.
  the moment a pin move makes O2 real. That is when the four golden blobs and the two
  verbatim asserts must be adopted in the SAME commit — and this file deleted.

This DELIBERATELY pins a default we did not choose (a negative matching a default pins that
default). Here the pin IS the record: the divergence must not be able to resolve silently.
"""

from __future__ import annotations

from pathlib import Path

import pytest

from portfolio_optimiser_claude import okf
from portfolio_optimiser_claude.ingest import materialize

SPEC = Path(__file__).resolve().parents[1] / "shared" / "ingest-spec.md"
GOLDEN = Path(__file__).resolve().parents[1] / "examples" / "ingest-golden-file"
INGESTED_AT = (GOLDEN / "ingested-at.txt").read_text(encoding="utf-8").strip()

_PROVENANCE_HEADING = "## 7. Provenance"
_INGEST_ACTOR = "process:okf-ingest"
_PRE_V1_LITERAL = "true"


def _provenance_section(text: str) -> str:
    """The §7 section body — heading to the next section. RED (ValueError) if §7 is gone."""
    start = text.index(_PROVENANCE_HEADING)
    end = text.find("\n## ", start + len(_PROVENANCE_HEADING))
    return text[start:] if end == -1 else text[start:end]


def _generated_row(text: str) -> str:
    """The §7 field-table row whose FIRST column is `generated` — "" if it is gone."""
    for line in _provenance_section(text).splitlines():
        if line.startswith("| `generated` |"):
            return line
    return ""


def _is_o2_mapping(value: str) -> bool:
    """The O2 shape as §7 defines it: an inline mapping naming the ingest actor in `by`."""
    stripped = value.strip()
    return (
        stripped.startswith("{")
        and stripped.endswith("}")
        and f"by: {_INGEST_ACTOR}" in stripped
        and "at:" in stripped
    )


# --- Spec side: §7 must keep defining O2 ---------------------------------------------


def test_section7_row_defines_the_o2_mapping() -> None:
    # RED if commons reverts V1 or renames the actor out of the row.
    row = _generated_row(SPEC.read_text(encoding="utf-8"))
    assert row, "§7 no longer carries a `generated` field row"
    assert _INGEST_ACTOR in row, f"§7 stopped naming the ingest actor: {row}"
    assert "`by`" in row and "`at`" in row, f"§7 stopped defining both subkeys: {row}"


def test_spec_no_longer_carries_the_pre_v1_literal() -> None:
    # V1's own claim, held against the text: `generated: true` is gone from the spec.
    text = SPEC.read_text(encoding="utf-8")
    assert "generated: true" not in text, "the pre-V1 literal is back in the spec"


def test_provenance_slice_is_a_slice_and_not_the_whole_spec() -> None:
    # Guards the anchor: a slice that degenerated into the full text would make the row
    # assertion green-but-dead (§12's anchor lesson, applied to §7).
    section = _provenance_section(SPEC.read_text(encoding="utf-8"))
    assert section.startswith(_PROVENANCE_HEADING), "the §7 anchor does not start at §7"
    assert "\n## " not in section, "the §7 anchor leaked a following section"
    assert "Honesty rule" not in section, "the §7 anchor leaked §1 prose"


# --- Emitter side: the pin still writes the pre-V1 literal ---------------------------


def test_emitter_still_writes_the_pre_v1_literal(tmp_path: Path) -> None:
    """RED the moment the pin starts emitting O2 — then adopt the golden and delete this."""
    bundle = tmp_path / "bundle"
    bundle.mkdir()
    materialize(GOLDEN / "manifest.json", bundle, INGESTED_AT)

    # Population control FIRST: a run that stopped emitting stamped files must not let the
    # divergence claim pass green on an empty set.
    stamped = [
        okf.parse_concept_file(path).frontmatter
        for path in sorted(bundle.glob("ingest-*.md"))
        if "generated" in okf.parse_concept_file(path).frontmatter
    ]
    assert stamped, "no stamped file was emitted — the divergence claim would be vacuous"

    for frontmatter in stamped:
        value = frontmatter["generated"]
        assert value == _PRE_V1_LITERAL, (
            f"the emitter no longer writes the pre-V1 literal ({value!r}) — adopt the O2 "
            "golden blobs and the verbatim asserts, then delete this file"
        )
        assert not _is_o2_mapping(value), "the emitter reached O2 — see the message above"


def test_o2_detector_is_not_a_tautology() -> None:
    # The negative above is only worth its RED if the detector can say yes. A detector that
    # always returned False would make it dead on arrival.
    assert _is_o2_mapping(f"{{ by: {_INGEST_ACTOR}, at: {INGESTED_AT} }}")
    assert not _is_o2_mapping(_PRE_V1_LITERAL)
    assert not _is_o2_mapping("{ by: human:jsmith@acme, at: 2026-01-01T00:00:00Z }")


# --- Red-proofs: the spec guards must fail on a detached spec (mutated copy) ----------


def test_guard_red_when_section7_row_removed(tmp_path: Path) -> None:
    text = SPEC.read_text(encoding="utf-8")
    row = _generated_row(text)
    copy = tmp_path / "ingest-spec.md"
    copy.write_text(text.replace(row + "\n", ""), encoding="utf-8")
    assert not _generated_row(copy.read_text(encoding="utf-8"))


def test_guard_red_when_actor_renamed_in_the_row(tmp_path: Path) -> None:
    # A detach-proof is not a value-proof: the row survives, under another actor.
    text = SPEC.read_text(encoding="utf-8")
    copy = tmp_path / "ingest-spec.md"
    copy.write_text(text.replace(_INGEST_ACTOR, "process:something-else"), encoding="utf-8")
    assert _INGEST_ACTOR not in _generated_row(copy.read_text(encoding="utf-8"))


def test_guard_red_when_pre_v1_literal_returns(tmp_path: Path) -> None:
    text = SPEC.read_text(encoding="utf-8")
    copy = tmp_path / "ingest-spec.md"
    copy.write_text(text + "\n\n`generated: true` is back.\n", encoding="utf-8")
    assert "generated: true" in copy.read_text(encoding="utf-8")


def test_guard_red_when_section7_heading_renamed(tmp_path: Path) -> None:
    # Fail-closed: no §7 heading means no anchor, and the guard must raise rather than
    # silently fall back to a wider (green-but-dead) slice.
    mutated = SPEC.read_text(encoding="utf-8").replace(_PROVENANCE_HEADING, "## 7. Stamping")
    copy = tmp_path / "ingest-spec.md"
    copy.write_text(mutated, encoding="utf-8")
    with pytest.raises(ValueError):
        _provenance_section(copy.read_text(encoding="utf-8"))