docs(okf): the mapping class is inexpressible, and T2 binds import not emission

A consumer measured our frontmatter gate against 0.2.0 and asked us to confirm
against a newer guard, correctly noting that a divergence would be a version
difference rather than a contradiction. Measured at 0.3.1: no divergence. Both
their results reproduce exactly.

Two things are sharper than what we documented yesterday:

ALL THREE ROUTES TO A MAPPING FAIL, each on a different rule -- flow {k: v} on the
disallowed value-start indicator, block on the nested-mapping check, dotted keys on
the key pattern. So the mapping CLASS has no expressible form; it is not a choice
between two shapes where one is better. That matters because OKF v0.2's `generated`
IS a mapping (`by` is required when it is present), so it cannot be expressed at
all. Pinned by a test asserting the three failures stay distinct.

T2 RUNS ON DOOR C ONLY. parse_frontmatter is referenced nowhere in the door A/B
persist path, so the same frontmatter that FAIL_SECUREs through import_bundle
passes screen_output unremarked. The grammar bounds what a consumer can RECEIVE,
never what a producer can EMIT -- which is the question a consumer's emitter design
was blocked on.

Also corrects one of our own rows: we reported "sources block list" as a single
FAIL_SECURE case. The parser distinguishes three shapes -- flat scalars parse
correctly, one key per item misparses silently to a string, two keys per item hard-
rejects. A one-element `verified:` block list passes today.

631 -> 642 passed. README item count synced.
This commit is contained in:
Kjell Tore Guttormsen 2026-07-27 09:11:22 +02:00
commit 2d5a9cd0c7
3 changed files with 74 additions and 4 deletions

View file

@ -44,7 +44,12 @@ items; this is the full list, each with the mechanism.
silently misparsed.** Gate T2 accepts a line-oriented subset deliberately — full
YAML is a larger parse-attack surface than a write-time gate needs. Nested mappings
and flow collections (`[a, b]`, `{k: v}`) are *rejected outright*, which fails
secure. The defect is between those two outcomes: a block sequence whose items carry
secure. **All three routes to a mapping fail, each on a different rule** — flow
(`{k: v}`) on the disallowed value-start indicator, block (`k:\n sub: v`) on the
nested-mapping check, and dotted keys (`k.sub: v`) on the key pattern — so the
mapping *class* has no expressible form, rather than one form being preferable to
another. What survives is scalars and flat lists of strings. The defect is between
those two outcomes: a block sequence whose items carry
exactly **one** key parses "successfully" into the wrong type —
`sources:\n - uri: https://e.com/a` yields the **string** `'uri: https://e.com/a'`,
not a mapping, while the same list with two keys per item hard-rejects. A pointer
@ -52,7 +57,14 @@ items; this is the full list, each with the mechanism.
(`attester:\n - resource: attesters/sql_equality.py` → WARN), whereas a top-level
`resource:` with a relative path correctly fails secure. The shape is not conformant
OKF, so a well-formed bundle will not produce it; a malformed or hostile one can, and
mode-b `import_bundle` writes the merged concept verbatim.
mode-b `import_bundle` writes the merged concept verbatim. Note the three block-list
shapes are *not* one case: flat scalars parse correctly, one key per item misparses
silently, two keys per item hard-rejects.
- **T2 constrains import, not emission.** The frontmatter grammar runs on
`okf.import_bundle` (door C) only — `parse_frontmatter` is referenced nowhere in the
door A/B persist path, so frontmatter that fails secure on import passes
`screen_output` unremarked. The grammar therefore bounds what a consumer can *receive*,
never what a producer can *emit*. Verified identical on 0.2.0 and 0.3.1.
- **Consequence: an OKF v0.2 concept cannot traverse the external-import path.** Both
of v0.2's backward-breaking migration targets are nested — `timestamp``generated.at`,
and body `# Citations` → a `sources` block list of mappings — so a conformant v0.2