feat(profiles): SEGMENTED_OKF_V0_2 so a segmented bundle can declare its spec

Neither shipped profile could do both: SEGMENTED_V1 names `bundle_id` and not
`okf_version`, OKF_V0_2 names `okf_version` and has no segmentation at all. The
sixth profile is where the two intersect. Additive, as upstream support always
is here -- a new profile, never a migration.

THE INDEX POLICY IS DECIDED, NOT INHERITED, and that is the part that was easy
to get wrong. Measured: OKF_V0_2.index has facets=None and per_directory=False,
while SEGMENTED_V1.index has both. Building on OKF_V0_2's index would have
produced a segmented bundle with no faceted index -- structurally valid, SPEC
conformant, and missing the surface a consumer reads. So the index comes from
SEGMENTED_V1 with both root keys named, and the spec declaration from OKF_V0_2.
The premise is asserted in the suite rather than trusted to stay true.

`SegmentationPolicy.adjudication_key` is the discriminator BETWEEN segmented
profiles. It has to be a field with a value: every 1-to-N branch keys on
`profile.segmentation is not None`, which both segmented profiles satisfy, so a
later step surfacing the adjudication marker on that check would write it into
SEGMENTED_V1 too and move a byte-pinned golden. `None` means the profile does
not surface adjudication state at all.

`okf_version`'s VALUE is not in this module and must never be: a profile names
a key, the caller owns its value (decision E1). A constant here would claim a
decision this library does not own and would be the one thing to chase on every
upstream release. Asserted.

Five existing profiles untouched, each still equal to a freshly constructed
copy, root keys pinned literally, and OKF_LATEST still DEFAULT -- adding a
profile is not a GA event.

Suite 926 -> 931.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/llm_ingestion_okf/profiles.py

@@ -892,6 +892,17 @@ class SegmentationPolicy:
     segment_id_key: str = "segment_id"
     offset_key: str = "source_offset"
     nav_label: str = "index"
+    # The discriminator BETWEEN segmented profiles, and the reason it has to be
+    # a field with a value rather than a presence check: every 1-to-N branch
+    # keys on `profile.segmentation is not None`, which BOTH segmented profiles
+    # satisfy. A step that surfaced the adjudication state on that check would
+    # write it into `SEGMENTED_V1` as well and move a byte-pinned golden.
+    #
+    # `None` means this profile does not surface adjudication state at all,
+    # matching the shape used everywhere else here. When set, it NAMES the
+    # frontmatter key and index facet; the value written under it is the
+    # adjudicator's, never this module's.
+    adjudication_key: str | None = None
 
 
 @dataclass(frozen=True)
@@ -1222,6 +1233,37 @@ SEGMENTED_V1 = BundleProfile(
 )
 
 
+# The sixth profile. A segmented bundle could not declare which upstream spec
+# it targets: `SEGMENTED_V1` names `bundle_id`, `OKF_V0_2` names `okf_version`,
+# and the two never intersected. Additive, as upstream support always is here --
+# a new profile, never a migration of an existing one.
+#
+# THE INDEX POLICY IS DECIDED HERE, NOT INHERITED, and that is the one thing in
+# this construction that is easy to get wrong. Measured: `OKF_V0_2.index` has
+# `facets=None` and `per_directory=False`, while `SEGMENTED_V1.index` has both.
+# Building the sixth profile on `OKF_V0_2`'s index would have produced a
+# segmented bundle with NO faceted index -- structurally valid, conformant, and
+# missing the surface a consumer reads. So the index comes from `SEGMENTED_V1`
+# with both root keys named, and the spec declaration comes from `OKF_V0_2`.
+#
+# `okf_version`'s VALUE is not here and must never be: a profile names a key,
+# the caller owns its value (decision E1). The value tracks the upstream Google
+# version and belongs to catalog; a constant here would claim a decision this
+# library does not own, and would be the one thing to chase on every upstream
+# release.
+SEGMENTED_OKF_V0_2 = BundleProfile(
+    types=OKF_V0_2.types,
+    frontmatter=OKF_V0_2.frontmatter,
+    paths=SEGMENTED_V1.paths,
+    index=replace(SEGMENTED_V1.index, root_frontmatter=("okf_version", "bundle_id")),
+    ownership=OKF_V0_2.ownership,
+    # Constructed rather than `replace`d off `SEGMENTED_V1.segmentation`: that
+    # attribute is typed `| None`, and the equality is asserted in the suite so
+    # this stays a fresh copy of the same policy plus the discriminator.
+    segmentation=SegmentationPolicy(adjudication_key="adjudication"),
+)
+
+
 # "The latest version supported as STABLE", not the latest present in this
 # module. It therefore keeps v0.1 UPSTREAM semantics for as long as v0.2 is
 # provisional, and flipping it is the GA event — one auditable action rather

tests/test_segmented_profile.py

@@ -111,3 +111,96 @@ def test_the_policy_is_frozen() -> None:
     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)