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

docs(okf-v0.2): the alignment track lands before the contract freezes

Browse source 
Everything built so far targets OKF v0.1. Upstream published v0.2 on
2026-07-25, so the plan records how the library relates to it and, more
importantly, who owns each decision.

Read from the spec itself rather than secondhand, which corrected two
readings that a summary had gotten wrong:

- STRICT_V1's `timestamp` is NOT a defect. Section 13.1 grants consumers a
  documented fallback to legacy `timestamp` precisely when `generated` is
  absent, and STRICT_V1 emits no `generated`. Nothing is asked of the wiki.
- The one measured shape problem is DEFAULT's `generated: "true"`, because
  v0.2 requires `generated.by` within `generated`. That key was not reserved
  in v0.1, so it was legal when written; v0.2 claimed the name. DEFAULT
  states commons' ingest-spec section 5 layer, so the fix is commons' call
  and is raised there as open question V1 rather than patched locally.

Two findings shrink the work. The canonical form for `generated` and a
single `verified` is an inline flow mapping, which the existing scalar
parser already round-trips as an opaque string, so block-list support is
only needed for `sources` and multi-verifier `verified` -- and only if a
named consumer asks. And the collision degrades safely: `_is_ingest_owned`
returns False for a v0.2 mapping, so a foreign concept is refused rather
than overwritten.

The track sits between Phases 3 and 4 because Phase 4 freezes the
cross-runtime contract. Freezing a v0.1 shape into two runtimes would let
the shared fixture suite certify the drift instead of catching it.

Self-imposed rule, since the spec does not require it: conform first, claim
after. Declaring `okf_version: "0.2"` is a MAY with no conformance
checkpoint, so claiming it early would be permitted -- and would be the same
class of true-sounding misleading claim as reporting a 0.2.0 measurement
under a 0.3.1 heading.

Also moves the guard 0.3.1 measurement procedure out of session state and
into execution-order.md, where it belongs.

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 11:42:37 +02:00
commit ca453b2895
4 changed files with 291 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

9
CLAUDE.md
View file

@ -63,6 +63,15 @@ are the library baseline. First consumer: `portfolio-optimiser-claude`.
The two halves share the OKF contract and fixture suite, **not code**.
**Upstream version: everything above targets OKF v0.1.** Google published v0.2
on 2026-07-25 (two supersessions, both with documented consumer fallbacks; all
new fields optional). Alignment is a policy track between Phases 3 and 4, not a
phase: `docs/plan/okf-v0.2-alignment.md`. Two constraints bind here — the
`generated` marker `DEFAULT` emits sits in commons' ingest-spec §5 layer, so its
shape is commons' call, not ours; and `okf_version`'s value belongs to catalog
(decision E1). No profile may hard-code an upstream version, and no bundle
claims a version its shape has not earned.
Phase 4 preconditions (coordination, not unilateral moves):
- Lifts okr's reference implementations (`okf-check.mjs`, `okf-index.mjs`,
innboks libs) in agreement with okr and the marketplace catalog; the