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

docs(okf-v0.2): V1 moves off our own recommendation, on commons' finding

Browse source 
We carried (b) -- generated.by naming this library and its version. Commons
found it collides with ingest-spec's conformance clause: :29 requires a
conformant implementation to reproduce the shared goldens byte for byte, and
`generated` sits inside the mandatory ordered prefix. A producer's name and
version inside a shared fixture means no sibling implementation can reproduce
it, and Golden regression fires on every version bump with no contract change.

They measured it as normative-only for them, since examples/ingest-golden-*
does not exist in commons. Measured here, it is observable today: four fixtures
carry `generated:` on line 8 inside the byte-compared prefix, and
ingest-golden-file is both the shared fixture against the sibling
implementation and the baseline po-claude runs the pilot against.

So we back (d) -- `process:<fixed id>` per v0.2 section 7. Second reason,
visible only from this side: it keeps _is_ingest_owned an equality check.
Under (b) the collision gate must either prefix-match and ignore the version --
parsing a value we had just made structured -- or stop recognizing files an
earlier version wrote, which fails safe but breaks re-running a manifest across
a version bump.

The cost of (d) is recorded rather than minimized: producer identity leaves the
bundle, and a log does not travel through Door C. The decision stays commons'
to ratify.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2aKJxLejT9S8jYwoZ9fut
This commit is contained in:
Kjell Tore Guttormsen 2026-07-26 17:09:20 +02:00
commit d65231c3ce
1 changed files with 45 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -547,12 +547,51 @@ unearned-claim pattern that "conform first, claim after" exists to prevent.
**V1 — `generated`'s shape in `DEFAULT` (commons').** *No longer blocks our v0.2
support*, because D2 puts v0.2 in a new profile. Still raised with commons,
because `DEFAULT` keeps emitting a v0.2-reserved key with a v1-era value.
Recommendation to carry: `generated: { by: "llm-ingestion-okf/<v>", at:
<ingested_at> }`, deriving the machine-generated predicate from `generated.by`
instead of a bespoke boolean — spec-native, removes a hand-rolled key, costs a
`_is_ingest_owned` change and a fixture regeneration. If commons declines, the
deviation is documented, not patched here.
because `DEFAULT` keeps emitting a v0.2-reserved key with a v1-era value. Commons
confirmed authorship, verified our four premises against `okf/SPEC.md`
independently, and put it in their ratification queue as item 8. They are not
blocking us and we are not waiting on them.
**Our recommendation changed on their finding, 2026-07-26.** We carried
`generated: { by: "llm-ingestion-okf/<v>", at: <ingested_at> }` — call it (b).
Commons found that it collides with ingest-spec's own conformance clause: `:29`
requires a conformant implementation to reproduce the shared golden extractions
byte for byte, `:267` compares `expected-bundle/` byte for byte, and `generated`
sits inside the mandatory ordered prefix (`:149-152`). A producer's name and
version inside a *shared* fixture means no other conformant implementation can
reproduce it, and Golden regression fires on every version bump without any
contract having changed.
They measured the blast radius as normative-only for them —
`examples/ingest-golden-*` does not exist in commons. **It is observable here
today.** Four fixtures carry `generated:` on line 8 inside the byte-compared
prefix (`ingest-golden-file/…/ingest-orders.md`, `…/ingest-products.md`,
`ingest-golden-sql/…/ingest-metrics.md`, `ingest-golden-http/…/ingest-status.md`),
and `ingest-golden-file` is the shared fixture against the sibling implementation
— the same one po-claude runs the pilot against.
So we now back **(d)**, commons' fourth option: `generated: { by:
"process:<fixed id>", at: <ingested_at> }`, using v0.2 §7's explicit
`process:<id>` actor form. Two measured reasons, the second visible only from
this side:
1. The value becomes constant, so the shared fixture stays producer-neutral and
version-stable.
2. `_is_ingest_owned` (`materialize.py:131-150`) stays an equality check. Under
(b), `<our actor>` carries a version, so the collision gate must either
prefix-match and ignore the version — parsing a value we had just made
structured — or stop recognizing files an earlier version wrote, which fails
safe but breaks re-running the same manifest across a version bump.
**The honest cost of (d), stated so the option set is not skewed our way:**
producer identity leaves the bundle. `ingest_manifest` still names the manifest
and §8 logging still holds the producer here, but a log does not travel with the
bundle through Door C. If tool-level traceability inside the artifact is a
requirement, (b) is right and `:29` is the price to ratify deliberately.
Either way the decision is the operator's via commons' queue, not ours. Our only
ask: if (d) is ratified, we want it before freezing a v0.2 fixture carrying
`generated`, so the regeneration happens once.
**V2 — Which D1 direction?** (c) recommended above; needs a decision before code
because it determines whether `mypy --strict` churn lands across the existing