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

docs(guard): re-measure the OKF grammar across four guard points, pin holds

Browse source 
Order G34 asked whether the corpus-wide rejection of a conformant `sources`
block reproduces against guard 1.1.0, on the premise that 1.1.0 introduced a
mapping-key allowlist on 08-21. It does reproduce, and the premise is off by
one release: v1.1.0 is dated 08-13 and carries no allowlist. The allowlist is
`5870483`, nine commits past that tag and carrying no tag of its own -- its
`__version__` still reads 1.1.0.

Measured, each point extracted with `git archive` and put on PYTHONPATH ahead
of the venv, resolved version confirmed per run. The conformant variant is 0
merged and the control 34 of 34 at 0.3.4, 1.0.0, 1.1.0 AND the allowlist
commit; the control merging is what shows the harness can pass at all. Seven
candidate `sources` carriers, and none that names a `resource` merges at any
of the four points, because `resource` is deliberately off the allowlist while
SPEC 5.1 makes it REQUIRED inside an entry.

Two things the plan did not know. v1.1.0 closed the one-key block sequence,
which the 2026-08-02 measurement recorded as the only shape carrying a section
10 pointer through Door C, so `unverified_references` is empty by construction
at >=1.1. And the allowlist commit moves this library's own goldens from 4 of
9 to 8 of 9 concepts through Door C, the `generated` stamp being exactly the
shape it admits.

The pin therefore holds at `>=0.3,<0.4` / `v0.3.4`. Lifting to v1.1.0 is
behaviour-free here (595 pass, the one red being the pin assertion itself) and
buys nothing on this axis; the gain sits on an untagged commit, and pinning
one trades a release channel for a moving target. The condition to revisit is
a fact, not a date: a guard tag containing `5870483`.

The 2026-08-02 table is left standing and dated rather than rewritten -- it is
true of the version it names.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-23 19:26:42 +02:00
commit 32b4b76dc4
1 changed files with 41 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1733,6 +1733,47 @@ empty against everything conformant; and if they fix their item 3, today's only
pointer path closes too. Neither is an argument for leaving it unfixed — an
advisory with nothing to report is the better outcome. Sent to them 2026-08-02.
**Re-measured across four guard points, 2026-08-23 (order G34).** The paragraph
above is true of `v0.3.4` and has been overtaken twice since. Each point was
`git archive`d out of the guard's repo and put on `PYTHONPATH` ahead of the venv,
resolved version confirmed on every run; this library's suite is green at all of
them (595 passed, and the single red is `test_guard_version_is_inside_the_pin`,
which is the pin assertion itself rather than a behaviour). Seven candidate
carriers for a `sources` entry, one concept each, through `okf.import_bundle`:
0.3.4 1.1.0 HEAD
- resource: X refuse refuse refuse
title: Y (SPEC 5.1 form)
[{ id: a, resource: X }] refuse refuse refuse
- { id: a, title: Y } refuse refuse MERGE
- { id: a, resource: X } refuse refuse refuse
{ id: a, title: Y } refuse refuse MERGE
- resource: X (one-key block seq) MERGE refuse refuse
- https://example.org/a (plain scalar) MERGE MERGE MERGE
Two things moved. `v1.1.0` closed the one-key block sequence, which is the guard's
own item 3 and the single pointer path the paragraph above names, so
`unverified_references` can no longer fire on any shape at `>=1.1` — the advisory
is now empty by construction rather than by grammar accident. And an untagged HEAD
commit (`5870483`, 2026-08-21) admits a flow mapping whose every key is on a
nine-name allowlist; that is what moves this library's own goldens from 4 of 9 to
8 of 9 concepts through Door C, the `generated: { by: …, at: … }` stamp being
exactly the shape it admits.
`resource` is deliberately off that allowlist, and SPEC 5.1 makes `resource`
REQUIRED within a `sources` entry, so **no carrier naming a `resource` merges at
any of the four points measured**. A conformant `sources` block has no admitted
form at the pinned version or ahead of it. That is a contract question with a
stated security reason behind it, not a calibration setting, and it stays the
guard's.
**The pin holds at `>=0.3,<0.4` / `v0.3.4` (decided here, 2026-08-23).** Lifting to
`v1.1.0` is behaviour-free for this library and buys nothing on this axis, because
the allowlist is not in that tag: the whole gain sits on an untagged commit, and
pinning one would trade a release channel for a moving target. The condition to
revisit is a fact rather than a date — a guard tag that contains `5870483` — and
the 4-of-9 to 8-of-9 line above is what it would buy.
Still theirs, and still open: whether a non-`.md` code file inside a bundle is
within `okf.import_bundle`'s mandate. Nothing above answers it — this decision
covers what *we* do with a pointer, not what the guard owes for the thing pointed