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

docs(k3): round 22, frontmatter a YAML reader reads back the same

Browse source 
K3-22's report, CHANGELOG under [Unreleased], and two corrections of a
sentence measured false.

README and CLAUDE.md both said of the flow form "both are valid YAML, and a
real YAML consumer recovers the same structure from either". An unquoted URL
with a query string inside a flow mapping is not valid YAML for PyYAML, and
the quoted form is refused by the pinned guard; the paragraph now states the
limit. CLAUDE.md also records the K3-22 invariant and the new refusal of a
`--frontmatter` flow value with such a leaf.

Measured, fix `ed0418f` against base `0308169`, each tree built twice from
frozen exports: five-document project 0 files moved; R761 XML and HTML 1 line
each; K2 default 42 `title` lines, after which 454 of 454 frontmatters parse
and read back the same (base 413 parse, 412 read back). hit@k on R761 base =
fix, S1-S6 6/6 at hit@1/8/50 at both k, KP rank 1; okf check 32 of 32 payloads
0 findings over 16 rules; K2 pin 7 passed in the export.

Found outside the order: the pinned guard refuses nearly every segmented
concept okf writes, on its scalar flow sequences (`source_offset`,
`references`, `derived`) -- identical before and after, so older than K3-22.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-11 11:47:40 +02:00
commit e717b1c87a
4 changed files with 350 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

11
README.md
View file

@ -858,8 +858,15 @@ frontmatter parser is line-oriented. It reads inline **flow** mappings
(`executor: { resource: …, receipt: [ … ] }`) as opaque values that round-trip
unchanged, but it cannot read the block form — two block mappings that both
carry a `resource` collapse into one namespace and the first is lost. Write the
flow form; both are valid YAML, and a real YAML consumer recovers the same
structure from either.
flow form, and know its limit: it is valid YAML only while every plain value
inside it avoids what ends a flow scalar — `,`, `[`, `]`, `{`, `}`, and for
PyYAML also `?` — as well as `": "`, `" #"`, a trailing `:` and a leading YAML
indicator. Within that limit a YAML consumer recovers the same structure from
either form. Beyond it no flow form works: quoting satisfies PyYAML, but the
guard refuses a quoted value inside a flow mapping, so this library refuses
such a value rather than write frontmatter a reader cannot parse. An earlier
version of this paragraph said "both are valid YAML" without that limit; it was
measured false for an unquoted URL with a query string.
## Non-goals