1
0
Fork 0

fix(okf): a flow sequence admits '#' and ':' where YAML reads them as text

1.4.0 refused a flow-sequence scalar element carrying '#' or ':' anywhere.
okf writes `references: [...]` as a flow sequence of doc links, and an
entry may carry a #fragment or a scheme://. claude-code-llm-wiki measured
parse_frontmatter raising on 2 038 of 5 467 concepts of a bundle okf
produced (2026-09-17); reproduced here on the same bundle, 2 038 / 5 467
before and 0 / 5 467 after (0 / 4 466 and 0 / 5 530 on the two other
builds).

The two characters are now refused by position, where PyYAML 6.0.3 gives
them a meaning: '#' opening the element or following whitespace (a
comment), ':' opening or ending the element or preceding whitespace (a
mapping). Elsewhere they are scalar characters. The rest of the refused
set, the indicator rule and the no-mixing rule are unchanged.

Chosen over admitting the characters wholesale because `[a: b]` is a
mapping and `[a #b]` a comment to YAML; admitting those would hand the
consumer a value YAML does not read. The position checks are substring
tests, no regex: CPU time stays linear in element count and length
(100k -> 800k), about 10 % over 1.4.0, inside the existing 2 s bound.

Pinned upstream corpus unmoved at 6 / 53. 910 passed (+17), coverage
exit 0, redos-sweep exit 0, 45 LIMITATIONS entries.
This commit is contained in:
Kjell Tore Guttormsen 2026-09-23 12:44:09 +02:00
commit 639da03f8c
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
4 changed files with 119 additions and 6 deletions

View file

@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Fixed — a flow sequence refused `#` and `:` where YAML reads them as text
`1.4.0` refused a flow-sequence scalar element carrying `#` or `:` anywhere.
okf writes `references: [...]` as a flow sequence of doc links, and an entry
may carry a `#fragment` or a `scheme://`. A consumer measured the cost
(claude-code-llm-wiki, 2026-09-17): `okf.parse_frontmatter` raised on **2 038
of 5 467** concepts of a bundle okf itself produced, so `okf.import_bundle`
returned a parse error instead of a verdict for 37 % of it. Reproduced here on
the same bundle before the fix (2 038 / 5 467); after it, **0 / 5 467** (and
0 / 4 466 and 0 / 5 530 on the consumer's two other builds).
The two characters are now refused by position, where YAML gives them a
meaning, ground-truthed against PyYAML 6.0.3 on every test row: a `#` that
opens the element or follows whitespace opens a comment, and a `:` that opens
or ends the element, or precedes whitespace, opens a mapping. Both stay
refused there. Elsewhere they are scalar characters, so `a#b`, `x://y#z`,
`claude-cli://open` and `https://e.com:8443/a` parse as the strings YAML reads.
The rest of the refused set (`{ } [ ] , " '`), the scalar-indicator rule and
the no-mixing rule are unchanged.
The pinned upstream corpus is unmoved at **6 / 53** (`_okf-upstream` @
`3fcbb9f`); its binding constraint is the top-level block mapping, not this
rule. The predicate stays linear: CPU time doubles with each doubling of
element count and element length (100k → 800k), about 10 % over `1.4.0`.
### Changed — documentation surfaces caught up with `1.3.0` and `1.4.0`
README, ADOPTION-BRIEF and BRIEF named `1.3.0` after the `1.4.0` tag. README
also said `resource` is not on the frontmatter allowlist and that a `sources`
block list of mappings is refused (both false since `1.3.0`), and described the
`resource` https-allowlist without saying it covers the top-level `resource`
only — `sources[].resource` is never URL-validated. LIMITATIONS listed
`tags: [a, b]` among the routes that fail (false since `1.4.0`). All corrected.
## [1.4.0] — 2026-09-08
### Added — `tags: [a, b, c]`, the one flow-sequence form SPEC §4.1 writes out