docs(okf-v0.2): supporting the latest OKF version becomes standing policy
Operator directive 2026-07-26: the library always supports the current
latest version of Google OKF. v0.2 shipped 2026-07-25, so v0.2 support is
committed work rather than something a consumer has to request. This
overrides the previous default answer to open question V3 ("no until a
named consumer asks"), which is kept in the plan marked superseded so the
override reads as deliberate.
Support is additive: a new profile, never a migration of the existing two.
That single design choice is what makes an always-latest policy sustainable,
and it resolves the tension the directive would otherwise create with three
constraints that do not yield to it:
- DEFAULT states commons' ingest-spec section 5 layer, so its `generated`
shape is commons' call. Under the additive design this stops blocking us,
which takes commons off the critical path.
- STRICT_V1 mirrors the proving consumer's ratified contract; changing
another repo's contract from here would violate O2.
- v0.2 defers the attestation receipt and verdict wire formats upstream, so
the format is supportable and the unspecified runtime is not. It re-enters
scope when upstream specifies it.
This is also the first time the phase-3 profile abstraction is forced by
something outside this repo rather than by a second consumer, which is the
better test of whether the seam was cut in the right place.
Deliverables D1-D6 replace the earlier decision-round framing: a frontmatter
model that can carry block lists (`sources`, multi-verifier `verified`), an
OKF_V0_2 profile plus an OKF_LATEST alias whose moving-target tradeoff is
documented rather than hidden, Door C conformance against the consumer
tolerance rules, `Attested Computation` round-trip, v0.2 golden fixtures, and
a release-checklist re-check so the standing policy cannot decay silently.
Two new assumptions carry the weight. V-A7 forbids any profile from emitting
`timestamp` together with a malformed `generated`, since that combination
would have neither a valid `generated.at` nor an eligible section 13.1
fallback. V-A8 validates our own v0.2 fixture against upstream's reference
implementation, because every other test in the suite only asks whether we
agree with ourselves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2aKJxLejT9S8jYwoZ9fut
This commit is contained in:
parent
ca453b2895
commit
cb23de4700
3 changed files with 257 additions and 171 deletions
31
CLAUDE.md
31
CLAUDE.md
|
|
@ -63,14 +63,29 @@ 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.
|
||||
### Upstream version policy (standing, non-negotiable)
|
||||
|
||||
**The library always supports the current latest version of Google OKF.** Set by
|
||||
the operator 2026-07-26. Phases 1–3 were built against v0.1; v0.2 shipped
|
||||
2026-07-25, so v0.2 support is committed work — not contingent on a consumer
|
||||
asking for it. Plan: `docs/plan/okf-v0.2-alignment.md`.
|
||||
|
||||
Support is **additive, expressed as a new profile**, never a migration of
|
||||
existing ones. This is what makes the policy sustainable instead of a recurring
|
||||
crisis, and it is bounded by three facts that do not yield to it:
|
||||
|
||||
- `DEFAULT` states commons' ingest-spec §5 layer — its `generated` shape is
|
||||
commons' call, raised there, never patched locally.
|
||||
- `STRICT_V1` mirrors the proving consumer's ratified contract — changing another
|
||||
repo's contract from here violates O2.
|
||||
- `okf_version`'s *value* belongs to catalog (decision E1).
|
||||
|
||||
Two invariants fall out: no profile hard-codes an upstream version, and no bundle
|
||||
declares a version its shape has not earned. Where upstream itself defers a
|
||||
contract — v0.2's attestation receipt and verdict wire formats — the format is
|
||||
supported and the unspecified runtime is not; it re-enters scope when upstream
|
||||
specifies it. Because "always latest" decays silently, the release checklist
|
||||
carries an upstream-version re-check.
|
||||
|
||||
Phase 4 preconditions (coordination, not unilateral moves):
|
||||
- Lifts okr's reference implementations (`okf-check.mjs`, `okf-index.mjs`,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue