docs(okf-v0.2): correct five Test A/GA claims V1 made stale

The pilot reads this section as instructions, and V1 (8318605) moved
premises underneath it while the tag it points at stayed still.

- A-E1: passing at v0.5.0a2 is not a promise DEFAULT's bytes never move.
  The expectation is anchored to the upstream axis; DEFAULT also tracks
  commons' ingest-spec axis, and V1 moved that one.
- A-E1: the runner reported the MAF wrapper has the same shape as
  po-claude's (three positional args, no `profile`), and re-exports the
  library symbol, so the two profile calls have somewhere to land.
- A-E1: our empty-diff span covers our examples/ only; the runner holds
  a fourth golden set we cannot pre-measure.
- A-E5: the `:164`/`:144` literals still describe the tag but no longer
  `main`; dated rather than swapped.
- A-E5: re-run-in-place was recorded as undecided. It is decided, and
  was already true at the tag — measured by reading v0.5.0a2, not
  inferred from main.
- GA table: two rows rest on "DEFAULT is byte-stable", which V1 ended.
  Plus the input the release-exposure report must carry — a value-literal
  `generated` predicate fails OPEN against the O2 form, so byte-clean
  goldens are not evidence a consumer is unaffected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X974G3Z7yXzdXK2nHnm11h
This commit is contained in:
Kjell Tore Guttormsen 2026-08-09 13:04:10 +02:00
commit fcb6e4c2c9

View file

@ -913,7 +913,20 @@ Two consequences worth stating, since neither is cosmetic:
- **Do not assume po-claude's call-path finding transfers.** Their adapter took
three positional arguments and exposed no `profile` parameter, which is what
made A-E1 measure the library API rather than their pipeline. Whether the MAF
side has the same shape is theirs to report, not ours to predict.
side had the same shape was theirs to report, not ours to predict — **and they
reported it 2026-08-09: the same shape.** Their public wrapper also takes three
positional arguments and exposes no `profile` parameter. It does not block the
test, because they re-export `materialize_bundle` itself, so a scratch-venv run
can call the library symbol directly under each profile without touching their
wrapper or a line of their run path. A-E1 therefore measures the library API on
their side too. Closing the wrapper gap is theirs, and they have placed it with
their v0.4.0+ adoption decision rather than here.
- **The span measurement above does not cover every golden the runner holds.**
Our `git diff` spans this repo's `examples/`. The runner has a fourth golden
set of their own with no counterpart here, going through the same materializer,
and they will report that outcome separately. Worth stating rather than leaving
implicit: an empty diff across our three goldens is evidence about our fixtures,
not about theirs.
**Procedure.** In a scratch venv, install the package at the `v0.5.0a2` tag —
**not `v0.5.0a1`, which is abandoned** (see above). Take
@ -925,6 +938,18 @@ output is the baseline. Materialize it twice with the *same* explicit
- **A-E1** The `DEFAULT` run is byte-identical to what their currently pinned
version produces. Support is additive; if this fails we have broken a v0.1
consumer and the pilot stops here.
**A-E1 passing is not a promise that `DEFAULT`'s bytes never move, and the
distinction stopped being theoretical on 2026-08-09.** The expectation is
anchored to the UPSTREAM axis: support for a new Google OKF version is
additive, so no upstream release moves an existing profile. `DEFAULT`
additionally states commons' ingest-spec layer, which is a separate axis it
tracks by definition — and commons executed V1 there (`54e0ec7`), so
`DEFAULT`'s `generated` value changed in this repo's `main` (`8318605`). That
change is **not** in `v0.5.0a2` and is therefore not what this test measures:
at the tag `DEFAULT` still writes `generated: true`, measured. Reading A-E1's
pass as byte-stability across releases would be the
expectation-outlives-its-decision class this section has already suffered twice.
- **A-E2** The v0.2 run differs from `DEFAULT` **only in frontmatter**. Body
bytes identical, filenames identical. *Revised on po-claude's measurement:*
the original text said "only **inside** the frontmatter block", which no
@ -983,10 +1008,33 @@ output is the baseline. Materialize it twice with the *same* explicit
there, `_is_ingest_owned` having since gained a per-manifest stem check that
narrows ownership further without touching the literal.
Distinct from this, and **not** a pilot expectation because the requirement is
undecided: whether a `DEFAULT`-written bundle may be re-run **in place** under
`OKF_V0_2` — i.e. whether the predicate accepts both the v0.1 stamp and the
v0.2 form. That is a D2 requirement question standing with the operator.
**Corrected 2026-08-09, and dated rather than swapped.** The cited `:164` /
`:144` literals were accurate for v0.3.2 and for `main` when the paragraph was
written, and they still describe **`v0.5.0a2`** — the tag the pilot installs,
which is the only version this expectation is measured against. They no longer
describe `main`: V1 moved both sides behind `OwnershipPolicy` (`stamp` /
`owns`), so the coupling is now named rather than implicit. What A-E5 actually
tests is the coupling, and that is unchanged; only the place it lives moved.
Distinct from this: whether a `DEFAULT`-written bundle may be re-run **in
place** under `OKF_V0_2` — i.e. whether the predicate accepts both the v0.1
stamp and the v0.2 form. **This was recorded here as undecided; it is decided,
and it was already true at the tag the pilot installs.** Measured by reading
`v0.5.0a2` rather than inferred from `main`: `OwnershipPolicy.owns` returns
true for the literal `true` in its first branch, before the actor is consulted
at all, and the rest of `_is_ingest_owned` at that tag is the per-manifest stem
check a `DEFAULT`-written file already satisfies. It remains outside the
numbered expectations because the procedure does not ask for that run — but a
runner who does it will not hit `collision_unstamped`, and should not report
that as a surprise.
On `main` the same recognition is a **tested** promise rather than a property
nobody exercised (`345684b`). Recognition is ONE-WAY by decision: a profile
carrying an actor owns the older literal stamp, so a pre-V1 bundle re-runs in
place and a spec release costs a consumer a re-run and nothing more; the
reverse is refused, a profile without an actor failing rather than replacing a
file whose shape it does not read (V-A3). The refusal direction is the half
that carries the safety, and it is asserted directly rather than implied.
- **A-E6** The root `index.md` declares `okf_version: 0.2` in a **frontmatter
block opening the file** — the first bytes are `---\nokf_version: 0.2\n---\n\n`
— with the value **unquoted** and **no UTF-8 BOM**.
@ -1284,6 +1332,26 @@ plainly is more useful than an invitation to review.
other, and consumer trees move — the wiki's document count moved by two between our
reading and their reply.
**Two rows went stale on 2026-08-09, and the table is the deliverable rather than
a summary of one.** The `portfolio-optimiser-claude` and `portfolio-optimiser`
rows both rest on "`DEFAULT` is byte-stable", which V1 (`8318605`) ended: every
concept file Door A writes under `DEFAULT` now changes one line. The re-run those
rows ask for is still the right instruction — it *is* the whole cost — but its
expected result is "one changed line per generated file", not byte-identity, and
"if they do nothing" stops being "nothing changes" for a consumer that pins a
release carrying V1.
**One input the release-exposure report must carry, found by a pilot rather than
by us.** A consumer answering "did this library write this file?" with a predicate
that compares `generated` against the literal `true` does not fail loudly against
the O2 form — it fails **open**, silently classifying this library's own output as
not-ours. The consequence is a gate that stops firing rather than one that fires
wrongly, so it does not surface in a check that only compares bytes, and a
consumer whose goldens still match can hold one unnoticed. The report therefore
asks every consumer to look for a value-literal `generated` predicate by name,
instead of treating the shape change as inert for anyone who reports no golden
churn.
### The ingest stamp's byte form is the ownership contract — decided 2026-08-02
Door A's `generated` value is `{ by: process:okf-ingest, at: <ingested_at> }`, and