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

feat(consume): parent reaches the reader -- excerpt field, body link, checker rule

Browse source 
K3-21 A. `okf consume` resolves a concept's `parent:` pointer -- a
`segment_id`, unique only inside one document's plan -- among the concepts
sharing its `source_file` (`consume.link_parents`, one pass, no file opened
again) and an excerpt carries `parent: { concept_id, title }`. Conditional
like `req_number`: a concept with no `parent` key moves no byte. A pointer
that lands nowhere is named `parent_unresolved: true`, never dropped.

The door writes ONE line into a heading-only body whose entry has a parent:
`Enclosing section: [<title>](/<bundle-relative path>)` (SPEC SS 5.1 lineage
through links, SS 6.1 the recommended absolute form and the kind in the
prose). Only such a body, so the segmented goldens' declared parents -- bodies
holding text -- are untouched. Appended AFTER structure derivation and
screened on its own (`_screened`, the `description` rule): read as body text
the link was derived into a second, unresolved `references` edge, measured on
the fixture. `segmentation.heading_only` is the one predicate the proposer and
the door share.

`okf check` gains its seventeenth rule, `parent_unfollowable`: a `parent`
that is not a concept_id and title, names its own excerpt, or names a concept
in neither `excerpts` nor `withheld` (together every considered concept).
Contract SS 8 point 6 added, the figure carries `parent`, and "additional
members are not read by the checker" now says the checker reads only the
members SS 8 names. The template tells the reader what `parent` is and that
SS 2.2 lets it read that one concept; `skill.CONDITIONAL_FIELDS` gains
`parent`. README and CLAUDE.md say what consume now reads.

Moved on purpose, each named: the SS 7.4 known-positive IS the contract
document, so `budget.known_positive` moves in every payload (13 238 / 12 893
/ 345 -> 14 455 / 14 083 / 372); `skills/okf-consume/` regenerated from the
segmented golden, whose plan declares s1 and s2 under s0 -- its example
payload now carries both parents; `test_bundle_identity` 16 -> 17 rules;
`test_shell_parent`'s byte test also accounts for the link line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-11 12:36:23 +02:00
commit 4f7bd61500
16 changed files with 319 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/consumption-contract.md
View file

@ -146,7 +146,7 @@ carries them.
## 8. The payload shape
The pre-pass MUST emit one JSON object with these members. Additional members
are permitted and are not read by the checker.
are permitted; the checker reads only the members this section names.
```json
{
@ -170,7 +170,8 @@ are permitted and are not read by the checker.
"title": "<the concept's own title>",
"req_number": "<the identifier the producer wrote, when there is one>",
"sources": [ { "resource": "<what the concept came from>" } ],
"source_pages": "<a locator into that resource, when the producer wrote one>"
"source_pages": "<a locator into that resource, when the producer wrote one>",
"parent": { "concept_id": "<the concept enclosing this one>", "title": "<its title>" }
}
],
"withheld": [ { "concept_id": "<bundle-local id>", "rule": "<why it was cut>" } ]
@ -206,6 +207,20 @@ are permitted and are not read by the checker.
by that producer under the same rule — and any allowlist drops it, leaving an
excerpt that names a document without naming the place in it. The prefix is a
prefix and never a substring: `resource_owner` is not a locator.
6. An excerpt SHOULD carry `parent` when its concept names the section that
encloses it, as the `concept_id` and `title` of the concept that pointer
resolves to in the same bundle — never the producer's own pointer, which a
reader cannot open without enumerating the bundle (§ 9.2). It is conditional
on the producer exactly as point 4's fields are, and § 6.4 forbids reading
its absence as a claim that the source has no enclosing section. A pointer
the pre-pass cannot resolve is named rather than dropped, as
`parent_unresolved` set to `true`, for point 4's reason, and is not a defect:
SPEC § 6.1, "Consumers MUST tolerate broken links". A `parent` names that one concept as reachable
in § 2.2's sense and names nothing else. The checker refuses
(`parent_unfollowable`) a `parent` that is not both members, that names its
own excerpt, or whose `concept_id` is in neither `excerpts` nor `withheld` —
together those name every concept the pre-pass considered (§ 5.2), so a
pointer outside them names nothing in the bundle.
## 9. Prohibitions