llm-ingestion-okf/tests/test_segmented_okf_v0_2_golden.py

"""The SEGMENTED_OKF_V0_2 golden: bytes, pinned.

A NEW golden directory, never an edit to the five that exist. Upstream support
is additive here, and the byte-pin is what makes "additive" a fact rather than
an intention: this file also asserts that the five prior goldens are untouched,
so a change that quietly moved one would fail HERE as well as in its own suite.

Modelled on `tests/test_segmented_golden.py`, NOT on `tests/test_golden.py`'s
`materialize_case`, which is Door A only -- it drives `materialize_bundle` from
a manifest, and this bundle comes through Door B's inbox.

CROSS-BUNDLE IDENTITY (PM decision B1), settled BEFORE this pin rather than
after it. Byte-pinning a bundle that carries `okf_version` is the moment its
concept IDs stop being adjustable, so the denotation has to be fixed first:

- A concept ID is BUNDLE-LOCAL and stable.
- Identity ACROSS bundles is the tuple `(bundle_id, concept_id)`, never the
  concept ID alone. The producer stamps `bundle_id` into every concept's
  frontmatter, so a consumer reads the whole tuple from one document.
- There is NO cross-bundle link form in v0.2. A consumer holding several
  bundles partitions per bundle; nothing here emits a syntax for pointing from
  inside one bundle into another.

Retrofitting a different denotation later would move a pinned golden, which is
the one thing byte-pinning exists to prevent.
"""

from __future__ import annotations

import json
from pathlib import Path

import pytest

from llm_ingestion_okf.guard_adapter import GateDecision
from llm_ingestion_okf.inbox import process_inbox
from llm_ingestion_okf.materialize import parse_frontmatter
from llm_ingestion_okf.profiles import SEGMENTED_OKF_V0_2
from llm_ingestion_okf.segmentation import parse_segmentation_plan

EXAMPLES = Path(__file__).resolve().parents[1] / "examples"
CASE = EXAMPLES / "ingest-golden-segmented-okf-v0-2"


def gate(text: str) -> GateDecision:
    return GateDecision(sanitized_text=text, disposition="warn")


def materialize(out_dir: Path) -> None:
    plan = parse_segmentation_plan(json.loads((CASE / "segmentation-plan.json").read_text("utf-8")))
    process_inbox(
        CASE / "fixture" / "inbox",
        out_dir,
        (CASE / "ingested-at.txt").read_text(encoding="utf-8").strip(),
        okf_type="reference",
        gate=gate,
        profile=SEGMENTED_OKF_V0_2,
        root_frontmatter_values={
            # Both values are fixture DATA read from the case, never constants
            # in this file. `okf_version`'s value tracks the upstream Google
            # version and belongs to catalog (decision E1); a literal here would
            # be this repository claiming a decision it does not own.
            "okf_version": (CASE / "okf-version.txt").read_text(encoding="utf-8").strip(),
            "bundle_id": (CASE / "bundle-id.txt").read_text(encoding="utf-8").strip(),
        },
        segmentation=plan,
    )


def tree(root: Path) -> dict[str, bytes]:
    return {
        path.relative_to(root).as_posix(): path.read_bytes()
        for path in sorted(root.rglob("*"))
        if path.is_file()
    }


def test_the_golden_rematerializes_byte_for_byte(tmp_path: Path) -> None:
    out_dir = tmp_path / "bundle"
    materialize(out_dir)
    expected = tree(CASE / "expected-bundle")
    actual = tree(out_dir)
    assert sorted(actual) == sorted(expected)
    for name in sorted(expected):
        assert actual[name] == expected[name], f"{name} diverges from the golden bytes"


def test_the_root_index_declares_both_keys(tmp_path: Path) -> None:
    """The whole reason this profile exists: a segmented bundle that also says
    which upstream spec it targets."""
    out_dir = tmp_path / "bundle"
    materialize(out_dir)
    front = parse_frontmatter(out_dir / "index.md")
    assert "okf_version" in front
    assert "bundle_id" in front


def test_the_bundle_satisfies_spec_section_11(tmp_path: Path) -> None:
    """SPEC section 11's three structural conditions, checked explicitly.

    Conformance is the FLOOR and not the proof -- section 11 checks frontmatter,
    not meaning, so a bundle can pass it while segmenting badly. It is still
    worth asserting, because failing it means the bundle is wrong in a way no
    consumer can work around.
    """
    out_dir = tmp_path / "bundle"
    materialize(out_dir)

    concepts = [path for path in sorted(out_dir.rglob("*.md")) if path.name != "index.md"]
    assert concepts, "the bundle has no concepts to check"
    for path in concepts:
        front = parse_frontmatter(path)
        assert front, f"{path.name} has no parsable frontmatter"
        assert front.get("type"), f"{path.name} has an empty or missing type"

    index = out_dir / "index.md"
    assert parse_frontmatter(index), "index.md has no parsable frontmatter"
    body = index.read_text(encoding="utf-8").split("---", 2)[2]
    assert body.strip(), "index.md has no body"


def test_concept_ids_are_bundle_local_and_carry_their_bundle(tmp_path: Path) -> None:
    """PM decision B1, asserted at the point where it becomes expensive to change.

    Every concept carries `bundle_id`, so `(bundle_id, concept_id)` is readable
    from a single document -- that tuple is what identity across bundles means,
    and the concept ID alone is never it.
    """
    out_dir = tmp_path / "bundle"
    materialize(out_dir)
    expected_bundle = (CASE / "bundle-id.txt").read_text(encoding="utf-8").strip()

    for path in sorted(out_dir.rglob("*.md")):
        if path.name == "index.md":
            continue
        front = parse_frontmatter(path)
        assert front.get("bundle_id") == expected_bundle, (
            f"{path.name} does not carry its bundle id; the identity tuple "
            "cannot be read from one document"
        )


def test_no_cross_bundle_link_form_is_emitted(tmp_path: Path) -> None:
    """There is no syntax for pointing from inside one bundle into another
    (B1/D5). A consumer partitions per bundle. This asserts the absence, so a
    later step cannot introduce one without a decision."""
    out_dir = tmp_path / "bundle"
    materialize(out_dir)
    # NOT `b-golden-segmented`, which is a PREFIX of this bundle's own id -- a
    # substring check against it fails on every file for the wrong reason, and
    # would have read as "a cross-bundle reference was emitted". Measured the
    # first time this test ran. A foreign id that is not a prefix is the only
    # thing that can distinguish the two.
    foreign = "b-some-other-bundle"
    own = (CASE / "bundle-id.txt").read_text(encoding="utf-8").strip()
    for path in sorted(out_dir.rglob("*.md")):
        text = path.read_text(encoding="utf-8")
        assert foreign not in text
        # And the known-positive half: the bundle DOES name its own id, so the
        # check above is looking at content that could have carried one.
        if path.name != "index.md":
            assert own in text


@pytest.mark.parametrize(
    "case",
    [
        "ingest-golden-file",
        "ingest-golden-sql",
        "ingest-golden-http",
        "ingest-golden-okf-v0-2",
        "ingest-golden-segmented",
    ],
)
def test_the_five_prior_goldens_are_untouched(case: str) -> None:
    """Additive, proven from this side too.

    Their own suites already compare them; this asserts they still EXIST with
    the same bytes on disk, which is what a `git`-less reader of this test can
    check. A new profile that moved an old golden would be a migration wearing
    an addition's clothes.
    """
    expected = EXAMPLES / case / "expected-bundle"
    assert expected.is_dir(), f"{case} lost its expected bundle"
    assert any(expected.rglob("*.md")), f"{case} has no concepts"