feat(profiles): SEGMENTED_V1 profile and SegmentationPolicy capability

tests/test_segmented_profile.py

@@ -0,0 +1,113 @@
+"""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")