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

docs(upstream): run the runbook against OKF at its new canonical repo

Browse source 
Operator GO 2026-08-23. Two findings outrank the change that triggered
the round.

OKF moved to GoogleCloudPlatform/open-knowledge-format (6265173). The
tree this repo pinned, knowledge-catalog path okf/, is now a frozen
snapshot by upstream's own notice, and the runbook's Trigger step named
it. The two trees have already diverged: the frozen copy carries a fix
(38c713f, eight tags: values as sequences rather than one plain scalar)
that the canonical repo does not.

The spec tightened without a version bump. SPEC.md still declares
Version 0.2, but every timestamp-valued key is now an ISO 8601 datetime
with an explicit offset, so a value that conformed in July does not
conform now under the same version number. Step 4 gained a fifth diff
class for it.

Our exposure is zero, measured: 10 of 10 timestamp values across the
four goldens already carry a Z offset, gated by _INGESTED_AT_RE. The
three tightened keys (stale_after, last_modified, usage_window) are
named but never written by any door. V-A8 at the new pin: 9/9 of our
bundle documents parse, 78/78 of upstream's do.

Two reference-reader behaviour changes recorded. A date-only
stale_after now reads as never stale rather than as stale -- silent,
fails open, and the class the black box cannot absorb. Timestamps now
survive a parse as written, so our ingested_at arrives as str where it
used to arrive as datetime.

No new profile: there is no new version to express. The pin move and
consumer notification are named as deliverables and deliberately not
taken here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013j8ZEcjiZQpz22fecNsyLZ
This commit is contained in:
Kjell Tore Guttormsen 2026-08-23 18:54:15 +02:00
commit b1c2f5ecee
2 changed files with 390 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -42,9 +42,27 @@ notice. So the re-check is an item on the release checklist — run it at every
release of this library, and record the result **even when unchanged**, because an
unrecorded check is indistinguishable from a skipped one.
Check `GoogleCloudPlatform/knowledge-catalog`, path `okf/`. A version bump appears
as a commit against `okf/SPEC.md` §12 and, in the v0.2 round, as an explicit
migration commit (`okf: migrate format and tooling to Open Knowledge Format v0.2`).
Check `GoogleCloudPlatform/open-knowledge-format`. **That is the canonical home of
the spec, the reference agent and the sample bundles as of 2026-08-21.** A version
bump appears as a commit against `SPEC.md` §12 and, in the v0.2 round, as an
explicit migration commit (`okf: migrate format and tooling to Open Knowledge
Format v0.2`).
**Do not check `GoogleCloudPlatform/knowledge-catalog`, path `okf/`.** That copy is
a frozen snapshot by upstream's own notice (`6265173`, "anything built against it
will drift out of date"), and this repo was pinned to it until the 2026-08-23 round.
Two consequences, both measured that round and neither hypothetical:
- **The two trees have already diverged**, and not only in the direction you would
expect: the frozen copy carries a fix (`38c713f`, eight `tags:` values written as
sequences rather than as one plain scalar) that the canonical repo does not. The
canonical tree is authoritative for the *spec*; it is not automatically a superset.
- **A round run against the frozen tree reports "no change" truthfully and
uselessly** — the exact shape of a negative result that is not a measurement.
*Prevents:* tracking a tree that has stopped being the thing you promised to track.
"Always latest" is a promise about an object with an identity, and the identity can
move without the version number moving.
## Step 1 — Pin before reading anything
@ -155,6 +173,15 @@ block form.
*Result, v0.2 round at `3fcbb9f`:* 13/13 green against
`examples/ingest-golden-okf-v0-2/`.
*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 —
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
fail:** feed it a deliberate `type: [unclosed` and confirm it raises before you
report the zeroes.
## Step 4 — Produce the diff, classified
From the spec's own "Changes from vN" section **plus** the example evidence,
@ -169,6 +196,15 @@ classify every change as:
- **Observed but undocumented** — present in an official bundle, not found in the
spec sections read. Record as unresolved. Do not silently promote it to either
category. (v0.2 round: a `not:` family in `metrics/gross-margin.md`.)
- **Tightened in place, no version bump** — the normative text narrows what a key
may hold, under the *same* version number. A value that conformed last round does
not conform now, and nothing in the version string says so. (2026-08 round: every
timestamp-valued key became an ISO 8601 datetime with an explicit offset, and
`SPEC.md` still declares Version 0.2.) Two things follow. First, do not reach for
the additive-profile machinery on reflex — there is no new version to express, and
minting one would declare a version upstream has not. Second, **"conformant with
v0.2" stops identifying one document**; the spec commit has to be named alongside
the version, which is what `okf_spec_commit` is for.
## Step 5 — Measure our exposure and each consumer's, in that order