llm-ingestion-okf/tests/test_segmented_profile.py

"""SEGMENTED_V1: the capability that lets one document become many concepts.

Additive in the strict sense the upstream-version policy demands. `DEFAULT`,
`STRICT_V1`, `STRUCTURED_V1` and `OKF_V0_2` keep the bytes they had, because
the new field is defaulted and every branch downstream is keyed on
`profile.segmentation is not None`.

That toggle is deliberately NOT `IndexPolicy.per_directory`. `STRICT_V1`
already sets that field True while Door B ignores it, so keying the capability
there would change `STRICT_V1`'s Door B output and break a byte-stability pin
that four consumers depend on. The measured trap is the reason the assertion
below is written as an identity check on all four profiles rather than on one.
"""

from __future__ import annotations

from dataclasses import replace

from llm_ingestion_okf.profiles import (
    DEFAULT,
    OKF_LATEST,
    OKF_V0_2,
    SEGMENTED_V1,
    STRICT_V1,
    STRUCTURED_V1,
    BundleProfile,
    SegmentationPolicy,
)

EXISTING = (DEFAULT, STRICT_V1, STRUCTURED_V1, OKF_V0_2)


# --- the capability -------------------------------------------------------


def test_only_the_new_profile_declares_the_segmentation_capability() -> None:
    assert SEGMENTED_V1.segmentation is not None
    for profile in EXISTING:
        assert profile.segmentation is None


def test_the_capability_is_not_keyed_on_per_directory() -> None:
    # STRICT_V1 already sets per_directory True and Door B ignores it. Keying
    # the 1-to-N branch there would silently change STRICT_V1's output.
    assert STRICT_V1.index.per_directory is True
    assert STRICT_V1.segmentation is None


def test_the_new_profile_writes_an_index_per_directory_and_names_bundle_id() -> None:
    assert SEGMENTED_V1.index.per_directory is True
    assert SEGMENTED_V1.index.root_frontmatter == ("bundle_id",)


def test_bundle_id_is_permitted_at_the_root_rather_than_demanded_by_the_policy() -> None:
    # The policy NAMES the key and fixes its position; the caller owns the
    # value (D5). Demanding it here would claim a decision this library does
    # not own -- Door B enforces the plan-requires-an-id rule instead.
    assert "bundle_id" not in SEGMENTED_V1.index.root_frontmatter_required


def test_the_new_profile_keeps_the_structured_facets_and_keys() -> None:
    assert SEGMENTED_V1.index.facets == STRUCTURED_V1.index.facets
    assert SEGMENTED_V1.frontmatter.order == STRUCTURED_V1.frontmatter.order
    assert SEGMENTED_V1.types is STRUCTURED_V1.types
    assert SEGMENTED_V1.paths is STRUCTURED_V1.paths


# --- the additivity proof -------------------------------------------------


def test_the_four_existing_profiles_equal_freshly_constructed_copies() -> None:
    # A defaulted field must not move any of them. `replace()` with no changes
    # reconstructs each profile through the dataclass constructor, so a field
    # that had become required -- or had picked up a non-default value -- shows
    # up here as inequality rather than as golden churn six steps later.
    for profile in EXISTING:
        assert replace(profile) == profile


def test_okf_latest_is_still_default() -> None:
    assert OKF_LATEST is DEFAULT


def test_a_profile_constructs_without_naming_the_new_field() -> None:
    minimal = BundleProfile(
        types=DEFAULT.types,
        frontmatter=DEFAULT.frontmatter,
        paths=DEFAULT.paths,
        index=DEFAULT.index,
    )
    assert minimal.segmentation is None


# --- the policy's own defaults -------------------------------------------


def test_the_policy_names_the_keys_it_governs() -> None:
    policy = SEGMENTED_V1.segmentation
    assert policy is not None
    assert policy.hierarchical_paths is True
    assert policy.bundle_id_key == "bundle_id"
    assert policy.segment_id_key == "segment_id"
    assert policy.offset_key == "source_offset"
    assert policy.nav_label == "index"


def test_the_policy_is_frozen() -> None:
    policy = SegmentationPolicy()
    try:
        policy.bundle_id_key = "other"  # type: ignore[misc]
    except Exception:
        return
    raise AssertionError("SegmentationPolicy must be frozen")


# --- the sixth profile: SEGMENTED_OKF_V0_2 ---


def test_the_sixth_profile_exists_and_carries_both_capabilities() -> None:
    """A segmented bundle that can also declare which upstream spec it targets.

    Neither shipped profile could: `SEGMENTED_V1` names `bundle_id` and not
    `okf_version`, `OKF_V0_2` names `okf_version` and has no segmentation at
    all. The sixth is what makes the two intersect.
    """
    from llm_ingestion_okf.profiles import SEGMENTED_OKF_V0_2

    assert SEGMENTED_OKF_V0_2.segmentation is not None
    assert SEGMENTED_OKF_V0_2.index.facets is not None
    assert SEGMENTED_OKF_V0_2.index.per_directory is True
    assert SEGMENTED_OKF_V0_2.index.root_frontmatter == ("okf_version", "bundle_id")


def test_the_index_policy_was_decided_rather_than_inherited() -> None:
    """The premise this profile's construction rests on, asserted.

    A profile built purely on `OKF_V0_2`'s index would have NO faceted index --
    measured: `OKF_V0_2.index.facets is None` and `per_directory is False` --
    and the adjudication marker would have nothing to project into. Inheriting
    would have looked correct and produced a bundle missing half its point.
    """
    from llm_ingestion_okf.profiles import OKF_V0_2, SEGMENTED_V1

    assert OKF_V0_2.index.facets is None
    assert OKF_V0_2.index.per_directory is False
    assert SEGMENTED_V1.index.facets is not None
    assert SEGMENTED_V1.index.per_directory is True


def test_the_two_segmented_profiles_are_distinguishable_by_a_policy_field() -> None:
    """`profile.segmentation is not None` CANNOT be the discriminator.

    Both segmented profiles satisfy it, so a later step keying the adjudication
    marker on it would write the marker into `SEGMENTED_V1` too and move a
    byte-pinned golden. The discriminator has to be a field with a value.
    """
    from llm_ingestion_okf.profiles import SEGMENTED_OKF_V0_2, SEGMENTED_V1

    assert SEGMENTED_V1.segmentation is not None
    assert SEGMENTED_OKF_V0_2.segmentation is not None
    assert SEGMENTED_V1.segmentation.adjudication_key is None
    assert SEGMENTED_OKF_V0_2.segmentation.adjudication_key == "adjudication"
    # And the discriminator is the ONLY thing that differs: the sixth profile's
    # segmentation policy is otherwise a copy, asserted rather than assumed so
    # a field added to one and not the other cannot pass unnoticed.
    from dataclasses import replace

    assert replace(SEGMENTED_OKF_V0_2.segmentation, adjudication_key=None) == (
        SEGMENTED_V1.segmentation
    )


def test_the_five_existing_profiles_are_untouched() -> None:
    """Additive means additive: every prior profile still equals a freshly
    constructed copy of itself, and its root keys are pinned literally."""
    from dataclasses import replace

    from llm_ingestion_okf.profiles import (
        DEFAULT,
        OKF_LATEST,
        OKF_V0_2,
        SEGMENTED_V1,
        STRICT_V1,
        STRUCTURED_V1,
    )

    assert DEFAULT.index.root_frontmatter == ()
    assert OKF_V0_2.index.root_frontmatter == ("okf_version",)
    assert SEGMENTED_V1.index.root_frontmatter == ("bundle_id",)
    for profile in (DEFAULT, STRICT_V1, STRUCTURED_V1, OKF_V0_2, SEGMENTED_V1):
        assert replace(profile) == profile
        assert profile.renderers is None
    assert OKF_LATEST is DEFAULT, "the GA alias is not flipped by adding a profile"


def test_the_sixth_profile_hard_codes_no_upstream_version_value() -> None:
    """A profile NAMES a key; the caller owns its value (decision E1).

    `okf_version`'s value tracks the upstream Google version and belongs to
    catalog, so a constant here would claim a decision this library does not
    own -- and would be the one thing to chase on every upstream release.
    """
    from llm_ingestion_okf.profiles import SEGMENTED_OKF_V0_2

    assert "okf_version" in SEGMENTED_OKF_V0_2.index.root_frontmatter
    assert "0.2" not in repr(SEGMENTED_OKF_V0_2.index.root_frontmatter)