docs(k3): round 24, a reason that became false is struck and the emitter stays flow
`_render_sources` gave three measured reasons for refusing to emit the block
form. Two of them fell with `28f9a4b` and are struck rather than left
standing: a block list no longer round-trips to an empty value (4 609 of
4 609 concept files), and B6's acceptance test can now pass.
Reason 2 STANDS and now carries the emission rule alone, re-measured by
reading `portfolio-optimiser` at `6eb58e5`: `read_provenance` returns
`UnreadableProvenance(reason="block-sequence")` for a block value. It is not
the guard's objection -- guard 1.4.0 reads the block form on 4 609 of 4 609
of the same files -- so the answer to "should our own emitter write block" is
NO, with the number that carries it, and the measurement that would make it
decidable is named in STATE rather than deferred without one.
The README paragraph said this library "cannot read the block form" where one
reader could and one could not. It now separates the two by KEY: `sources` in
either form through every reader, every other block mapping still refused,
with the D1b pointer intact.
Report: 222 lines, S7 form. Five deviations first, including the acceptance
sentence naming THREE flat readers rather than one, a `title` denominator of
7 372 rather than 5 372, and the `okf check` rule answered NO with a
measurement (`contract_check` holds 0 occurrences of `sources`, and
`consume` already writes `sources_unreadable` for the state a rule would
restate; `len(RULES)` is 17). Honesty limits name the one-key-wide set, the
block `verified:` fixture still reading empty, and the rendering not being
byte-identical to the source.
Suite 1807 passed / 1 skipped, rc 0, 98 s.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
28f9a4b540
commit
2d4f56dc6c
5 changed files with 326 additions and 27 deletions
43
README.md
43
README.md
|
|
@ -876,19 +876,36 @@ resource it points at: recovering the resource needs the structured reader.
|
|||
|
||||
One limit worth knowing before you write such a concept: §10.2 presents
|
||||
`executor` and `attester` as nested block mappings, and this library's
|
||||
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, 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.
|
||||
frontmatter parser is line-oriented. Which form it reads depends on the KEY,
|
||||
and the distinction is worth stating precisely, because this paragraph used to
|
||||
blur it:
|
||||
|
||||
- **`sources` in either form.** `consume.read_sources` has always read both,
|
||||
and since 2026-09-12 (K3-24) so do all three copies of the flat grammar
|
||||
(`materialize.parse_frontmatter`, which is public API, and the two internal
|
||||
ones). A block sequence of mappings is decoded into the flow rendering those
|
||||
readers round-trip; the entries never enter the document's key namespace.
|
||||
Measured against PyYAML 6.0.3 and the pinned guard 1.4.0 on 4 609 of 4 609
|
||||
concept files carrying a block `sources`, all three readers return the same
|
||||
entries both references do.
|
||||
- **Every other key, flow only.** `executor`, `attester` and any other block
|
||||
mapping are still skipped rather than parsed: two block mappings that both
|
||||
carry a `resource` would collapse into one namespace and the first would be
|
||||
lost, so they are refused instead. Reading them needs the structured reader
|
||||
(D1b).
|
||||
|
||||
Write the 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. That
|
||||
refusal is also why K3-24 is a reading change only: this library still emits
|
||||
flow, because a named downstream consumer classifies a block sequence as
|
||||
unreadable provenance even though the guard reads it.
|
||||
|
||||
## Non-goals
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue