feat(okf-v0.2): D5 — the v0.2 golden fixture, with okf_version in root frontmatter

Placement settled by catalog's own reading of upstream at the pinned commit
3fcbb9f: SS8:509-510 and SS12:773-775 both put `okf_version` in a bundle-root
`index.md` frontmatter block, and SS12 calls it the only place frontmatter is
permitted in an index. Catalog's spec says the opposite about the same file;
that divergence is theirs against upstream, and we conform to upstream.

The value never touches a profile. `OKF_V0_2.index.root_frontmatter` names the
key; the caller supplies the value through a new keyword-only
`root_frontmatter_values` mapping. That keeps V4/V-A5 intact - `okf_version`'s
value tracks the upstream Google version and belongs to catalog (E1), so a
constant here would claim a decision we do not own and would have to be chased
on every upstream release. In the fixture the value is fixture DATA
(`okf-version.txt`), not a literal in our source.

Ordering comes from the policy, not the caller's mapping: a dict preserves
insertion order, so two callers passing the same keys would otherwise emit
different bytes. A key the policy does not name is refused fail-fast, before
any disk mutation. Omitting the argument emits no block at all - SS12 is a MAY
and none of upstream's four reference bundles declares the key.

The block is written only when the index is CREATED, so a re-run into an
existing bundle stays byte-identical (A-E5).

Raw-byte assertions rather than parsed ones, on the committed fixture as well
as on fresh runs: catalog measured that a quoted value fails their shape regex
with exit 1 and that a BOM hides the marker while still exiting 0.
`yaml.safe_load` returns "0.2" either way and strips a BOM first, so a parsed
assertion masks exactly those two defects. Asserting the frozen fixture catches
what a self-comparison cannot - regenerating from a broken emitter moves both
sides together.

A-E6 is now placement-explicit (promised catalog in 99cf987), and separates the
two byte properties: BOM-free is a property of the file, unquoted is a property
of CATALOG'S GATE and not of OKF v0.2 - upstream's own SS12 example is quoted,
so their gate rejects the spec's canonical form.

README gains the upstream-version section it was missing; CLAUDE.md gains the
mechanism behind "no profile hard-codes an upstream version": a profile names a
key, a caller owns its value.

550 -> 559 tests. test_profile_threading's `OKF_V0_2.index is DEFAULT.index`
assertion is replaced rather than deleted: object identity was a proxy for "the
shipped profiles differ in no NAME-bearing field", which is what makes the
synthetic test profile necessary, so the guard now asserts that directly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013dgkSPjkLpACjMayd9R5jx

src/llm_ingestion_okf/materialize.py

@@ -13,6 +13,7 @@ import hashlib
 import logging
 import re
 import unicodedata
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -307,6 +308,36 @@ def link_in_index(
     index_path.write_bytes(f"{prefix}{line}\n".encode())
 
 
+def _render_root_frontmatter(values: Mapping[str, str], *, profile: BundleProfile) -> str:
+    """The root index's frontmatter block (§8, §12), or "" when nothing is
+    declared.
+
+    The policy names the keys and fixes their order; the caller supplies the
+    values. Ordering by the POLICY rather than by the mapping is what keeps two
+    callers passing the same keys from emitting different bytes — a dict
+    preserves insertion order, and a golden fixture would then depend on the
+    order a caller happened to build its argument in.
+
+    Values are written verbatim. `okf_version` must reach catalog's shape gate
+    unquoted, so nothing here may add quoting; the golden fixture asserts that
+    on raw bytes.
+    """
+    unknown = sorted(set(values) - set(profile.index.root_frontmatter))
+    if unknown:
+        raise MaterializationError(
+            f"root frontmatter key(s) {', '.join(repr(key) for key in unknown)} are not "
+            f"named by the {profile.index.name} policy, which pins "
+            f"{profile.index.root_frontmatter or '()'} — writing an unnamed key would "
+            "put a value in a file no reader of this contract looks at",
+            code="index_root_frontmatter_unexpected",
+        )
+    declared = [key for key in profile.index.root_frontmatter if key in values]
+    if not declared:
+        return ""
+    lines = "".join(f"{key}: {values[key]}\n" for key in declared)
+    return f"---\n{lines}---\n\n"
+
+
 def materialize_bundle(
     manifest_path: Path,
     bundle_dir: Path,
@@ -315,6 +346,7 @@ def materialize_bundle(
     allow_network: bool = False,
     http_get: HttpGet | None = None,
     profile: BundleProfile = DEFAULT,
+    root_frontmatter_values: Mapping[str, str] | None = None,
 ) -> IngestResult:
     """Materialize a manifest's extractions into an OKF bundle (§5).
 
@@ -335,10 +367,25 @@ def materialize_bundle(
     gate recognises, the concept filenames, and the index; it does NOT reach
     manifest type validation, which runs against `DEFAULT` (the two policies
     compare equal today). `STRICT_V1` is not supported here: its index policy
-    sets `per_directory`, `entries_match_directory` and `root_frontmatter`,
-    none of which this materializer honours.
+    sets `per_directory` and `entries_match_directory`, neither of which this
+    materializer honours.
+
+    `root_frontmatter_values` supplies the values for the keys the profile's
+    index policy names — `okf_version` under `OKF_V0_2` (§8, §12). The split is
+    deliberate: the profile names the key, the caller owns the value, because
+    `okf_version`'s value tracks the upstream Google version and belongs to
+    catalog (E1). Offering a key the policy does not name is refused fail-fast,
+    before any disk mutation. Omitting the argument emits no block at all — §12
+    is a MAY, and none of upstream's reference bundles declares it.
+
+    The block is written only when the index is CREATED. A re-run into an
+    existing bundle leaves it untouched, which is what makes the second run
+    byte-identical to the first (A-E5).
     """
     validate_ingested_at(ingested_at)
+    # Before any source access or disk mutation: a caller error here must not
+    # leave a partially written bundle behind.
+    root_frontmatter = _render_root_frontmatter(root_frontmatter_values or {}, profile=profile)
     manifest_file = Path(manifest_path)
     try:
         raw = manifest_file.read_bytes()
@@ -440,7 +487,7 @@ def materialize_bundle(
         for extraction in manifest.extractions
     }
     if not index_path.is_file():
-        write_bytes(bundle, profile.index.name, manifest.bundle_summary + "\n")
+        write_bytes(bundle, profile.index.name, root_frontmatter + manifest.bundle_summary + "\n")
     else:
         # Links whose target is an ingest-owned file removed this run MUST be
         # removed; all other links — curated and promoted — are preserved.