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

35
docs/plan/okf-v0.2-alignment.md
View file

@ -33,7 +33,22 @@ See D4.
## Provenance of the facts below — V-A1 is DISCHARGED
**Pinned 2026-07-26 to `3fcbb9f828c2f23d109c855ee403c3a4c81f3a96`** in
**RE-PINNED 2026-08-23 to `ad30107c31c06aec8a7d5636e0d1058118604e6f`** in
`GoogleCloudPlatform/open-knowledge-format` (2026-08-21, merge of
`okf-iso-datetimes`, 132 tracked files) — the canonical home since upstream moved
OKF out of `knowledge-catalog` and froze the copy under `okf/`. Ordered
2026-08-23; the round that measured the move is
`docs/plan/okf-2026-08-timestamp-tightening.md`, and the cost of the move to our
fixtures was measured at zero bytes before it was taken.
**The old hash below is not stale text — it is provenance.** Every fact in this
document was *read* at `3fcbb9f`, and rewriting the hash would give those facts a
provenance they do not have. What moves with the pin is the tree we measure
*against* from now on, plus V-A8, which is re-recorded at the new pin in the
verification table. What upstream changed between the two pins is the subject of
the tightening round, not of this document.
**Originally pinned 2026-07-26 to `3fcbb9f828c2f23d109c855ee403c3a4c81f3a96`** in
`GoogleCloudPlatform/knowledge-catalog` (2026-07-24, "Update SPEC.md"). v0.2
itself landed one commit earlier in `780fe9d30b5bbca8931256edf1d0290d6bda5462`
(2026-07-24, "okf: migrate format and tooling to Open Knowledge Format v0.2
@ -1864,11 +1879,23 @@ everything after. **Done 2026-07-26** (`1215f98`, `7bc366b`).
| V-A5 | No profile hard-codes an upstream version | Step 3 |
| V-A6 | Adding v0.2 support is behavior-neutral for v0.1 profiles | Golden suite byte-for-byte under `DEFAULT` **and** `STRICT_V1`; existing tests unmodified and green (C1 extended). **SUPERSEDED for `DEFAULT` 2026-08-09 — by commons, not by v0.2 support.** V1 moved `DEFAULT`'s `generated` and four goldens with it. The claim as written holds for what it was written about: adding v0.2 support changed no `DEFAULT` byte, and `STRICT_V1` is still byte-stable and its tests unmodified. A future session reading a golden diff here should not file it as a v0.2 regression |
| V-A7 | No profile can emit `timestamp` together with a malformed `generated` | Named construction-time test, same shape as C3's verdict reservation |
| V-A8 | A v0.2 bundle we emit is accepted by an independent v0.2 consumer | Validate the D5 fixture against upstream's reference implementation, not only against our own reader. **DONE 2026-07-31 @ `3fcbb9f`: 13/13.** Procedure is runbook Step 3a |
| V-A8 | A v0.2 bundle we emit is accepted by an independent v0.2 consumer | Validate the D5 fixture against upstream's reference implementation, not only against our own reader. **RE-RECORDED 2026-08-23 @ `ad30107`: 9/9 documents parse across all four goldens, 0 failures; 27/27 semantic-reader calls (`trust_tier`, `normalize_verified`, `is_stale`) return without raising.** Earlier: DONE 2026-07-31 @ `3fcbb9f`, 13/13 — the two counts are not comparable (different harness scope; see the note below). Procedure is runbook Step 3a |
V-A8 is the one that keeps this honest. Every other test asks whether we agree
with ourselves.
**Why the two V-A8 counts do not compare, 2026-08-23.** The 2026-07 harness
counted concept documents in one bundle; the 2026-08 harness walks all four
golden bundles and counts root `index.md` files too. A lower number is a wider
scope, not a regression. The re-run was put to a known-positive before its zeroes
were believed: a document with `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 — so the harness is shown able to
report both a failure and a positive. Types recovered at `ad30107`:
`ingested_at` → `str` (was `datetime` at `3fcbb9f`), `generated` → `dict`,
`sources` → `list`, `okf_version` → `float`. The float coercion is A-E6, still
real and still upstream's.
**Executed 2026-07-31, and it was nearly weakened on a false premise.** The
standing note said V-A8 had to be re-scoped to parse-and-render because "there is
no validator in `okf/`". Enumerating the tree instead of the subdirectory showed
@ -1946,7 +1973,9 @@ is also where an upstream reader change would be caught.
additions only).
4. V-A7 and V-A5 named tests present and failing-by-construction if removed.
5. V-A8: the v0.2 fixture validates under upstream's reference implementation.
**Done 2026-07-31 @ `3fcbb9f`, 13/13.** Re-run per upstream release via runbook
**Re-recorded 2026-08-23 @ `ad30107`: 9/9 documents, 0 parse failures, 27/27
semantic-reader calls clean.** Earlier: done 2026-07-31 @ `3fcbb9f`, 13/13.
Re-run per upstream release via runbook
Step 3a — it is a procedure, not a pytest test, because it needs PyYAML and
upstream's source and this package has exactly one runtime dependency.
6. Boundary grep-gate still empty (`sanitize|quarantine|lexicon` absent outside