open/llm-ingestion-okf
1
0
Fork 0
Code Issues Releases 1 Activity

docs(upstream): move the OKF pin to canonical ad30107, re-record V-A8

Browse source 
The operator authorized the move from `3fcbb9f` (frozen `knowledge-catalog/okf/`)
to `ad30107` in `GoogleCloudPlatform/open-knowledge-format`. Cost to our fixtures
was measured at zero bytes before the decision and is unchanged: `okf_spec_commit`
is a key `STRICT_V1` names, its value is the caller's under D5, and no shipped
fixture carries one.

The old hash stays in the alignment plan rather than being rewritten. Every fact
under that heading was *read* at `3fcbb9f`; replacing the hash would give those
facts a provenance they do not have. What moves is the tree we measure against.

V-A8 re-run at the new pin: 9/9 of our golden documents parse under upstream's
reader, 0 failures, 27/27 semantic-reader calls (`trust_tier`,
`normalize_verified`, `is_stale`) return without raising. The zeroes are
measurements — the harness was put to a known-positive in both directions first:
`type: [unclosed` raises `OKFDocumentError` while a well-formed control parses,
and `is_stale` returns True for a past `stale_after` and False for a future one.
Types recovered: `ingested_at` -> str (was datetime), `generated` -> dict,
`sources` -> list, `okf_version` -> float (A-E6, still upstream's).

The `38c713f` divergence is carried forward as a written known divergence rather
than left to evaporate with the pin, and it is now recorded at pin-level
precision. `38c713f` is not an ancestor of `3fcbb9f` (`merge-base
--is-ancestor` exits 1) — it landed three weeks forward of the pin we left, so
both the old and the new pin carry the bare-scalar `tags:` form and the move
loses nothing. The accurate statement is that canonical ships a form its own
frozen predecessor has already repaired.

The open question is closed rather than deferred, because it was cheap: across
129 tracked text files present in both trees, 9 carry frozen-only lines - 8 are
`38c713f` and the 9th is the freeze notice in `README.md`. Zero files are
frozen-only. The divergence is fully enumerated.

Runbook Step 3a gains the harness trap that cost this round a re-run: the
semantic readers take the frontmatter mapping, not the document, and passing the
document raises an AttributeError that reads like an upstream incompatibility.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-23 20:30:22 +02:00
commit e286b5a173
3 changed files with 109 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/upstream-okf-upgrade-runbook.md
View file

@ -155,12 +155,18 @@ Assert, over each file of the current version's golden bundle:
structures. Only an outside parser can.
2. The values arrive as the *shapes* the profile intends — `generated` as a
mapping, `sources` as a list of mappings — not merely as something that parsed.
3. `validate()` passes. Note what this does and does not buy: at `3fcbb9f`
`REQUIRED_FRONTMATTER_KEYS = ("type",)`, so it checks one key. Treating a green
`validate()` as "upstream accepts our bundle" would overclaim badly; the parse in
(1) and the shape assertions in (2) are where the signal is.
3. `validate()` passes. Note what this does and does not buy:
`REQUIRED_FRONTMATTER_KEYS = ("type",)`, so it checks one key — measured
unchanged at `3fcbb9f` and at `ad30107`. Treating a green `validate()` as
"upstream accepts our bundle" would overclaim badly; the parse in (1) and the
shape assertions in (2) are where the signal is.
4. The semantic readers upstream ships run over our frontmatter without raising —
at `3fcbb9f`: `trust_tier` (§5.3), `normalize_verified` (§5.2), `is_stale` (§5.5).
at `3fcbb9f` and at `ad30107`: `trust_tier` (§5.3), `normalize_verified` (§5.2),
`is_stale` (§5.5). **They take the frontmatter mapping, not the document.**
Passing the `OKFDocument` raises `AttributeError: 'OKFDocument' object has no
attribute 'get'` — a harness bug that reads exactly like an upstream
incompatibility if the traceback is not read. Cost this round: one re-run.
`OKFDocument.parse()` likewise takes the text only; there is no `path=` keyword.
**Record the type each value arrives as, not just that it parsed.** A real YAML
parser coerces, and the coercions are load-bearing facts about the value space —
@ -175,7 +181,8 @@ block form.
*Result, 2026-08 round at `ad30107`:* 9/9 of our bundle documents parse, across all
four goldens, with the three semantic readers running over each without raising;
78/78 of upstream's own bundle documents parse. Do not compare the two counts —
78/78 of upstream's own bundle documents parse. **Re-run 2026-08-23 when the pin
moved to `ad30107`: 9/9 parsed, 0 failures, 27/27 semantic-reader calls clean.** Do not compare the two counts —
the second harness asserted `validate()` on root `index.md` files too, which
correctly fails (an index carries no `type`), so it counts differently by
construction. **A clean sweep is worth nothing until the harness is shown able to