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

feat(check): the contract and the checker state the payload's v1.1 forms

Browse source 
C6. `docs/consumption-contract.md` now says what the pre-pass emits:

- SS 2.5 point 2: sub-questions are written in the bundle's terms and given to
  the pre-pass in ONE run where it takes several;
- SS 8's example is `okf-consumption/2` as shipped: `withheld` is the
  `{total, by_rule, nearest, complete}` mapping, `coverage` carries
  `absent_terms` and `weak`, an excerpt carries `text`, `text_sha256`,
  `passage` and `own_title`; point 1 closes the identity on `withheld.total`;
- point 7 keeps the falsified verdicts on record and states the one reading
  carried since v1.1, `weak`, with its rule: a word held in no form, or
  nothing delivered -- whether a word exists at all, which does not move with
  question style or corpus size the way the two shares did;
- point 8 the passage (`{start, end, of}`, `text_sha256` over the passage,
  `sha256` still the file's), point 9 several sub-questions in one run (one
  cut, `questions`, `subquestions`, per-sub-question coverage), point 10 a
  title inherited from the heading above, with `own_title`;
- SS 10 names this library's default ranking (BM25) and `--ranking fusion`.

`okf check` holds the two new forms a reader acts on: `passage_malformed`
(not whole numbers with 0 <= start < end <= of) and `subquestions_unindexed`
(not distinct indices into `questions`, or indices in a payload listing none).
17 -> 19 rules; the two tests that pin the published count move with it.
Each rule is held against a real payload (0 findings) and against that
payload broken six ways.

Editing the contract moved the SS 7.4 known-positive, measured once after the
edit: 19 837 -> 23 672 encoded, 19 358 -> 23 092 raw, delta 479 -> 580. The
example payload and `skills/okf-consume` are regenerated by the published
recipe and `okf check` reports 19 rules, 0 findings on them.

Suite on a clean tree after `git add`: 2443 passed, 2 skipped, 4 xfailed.
ruff, ruff format, mypy --strict clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-21 08:47:46 +02:00
commit 977040f575
11 changed files with 308 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

77
docs/consumption-contract.md
View file

@ -70,8 +70,9 @@ searches — and MUST NOT state one that stops at a single run.
to put the question into the bundle's terms. A bundle in one language and a
question in another share few tokens, and a pre-pass matching tokens then
ranks on almost nothing.
2. It MUST tell its reader to split a broad question into sub-questions and to
run the pre-pass per sub-question.
2. It MUST tell its reader to split a broad question into sub-questions written
in the bundle's own terms, and to give every sub-question to the pre-pass —
in ONE run where the pre-pass takes several (§ 8.9), otherwise one run each.
3. It MUST say that several runs are permitted and expected, and MUST NOT
contain a sentence forbidding a second run with other terms. Both the
`withheld` near misses (§ 5.3) and § 2.2 exist so that the second run can
@ -203,7 +204,7 @@ are permitted; the checker reads only the members this section names.
```json
{
"contract": "okf-consumption/1",
"contract": "okf-consumption/2",
"bundle": { "bundle_id": "<id>", "ref": "<commit or content identity>" },
"budget": {
"unit": "<named unit>",
@ -213,10 +214,13 @@ are permitted; the checker reads only the members this section names.
"known_positive": { "case": "<name>", "expected": 10406, "measured": 10406 }
},
"denominators": { "considered": 439, "withheld": 401, "delivered": 38 },
"question": "<the question asked>",
"coverage": {
"question_terms": ["<the terms the pre-pass read the question as>"],
"unanswered_in_bundle": ["<those no concept in the bundle answers>"],
"unanswered_in_payload": ["<those no delivered excerpt answers>"]
"unanswered_in_payload": ["<those no delivered excerpt answers>"],
"absent_terms": ["<those the bundle holds in no form at all>"],
"weak": false
},
"excerpts": [
{
@ -225,20 +229,31 @@ are permitted; the checker reads only the members this section names.
"sha256": "<hex digest of the concept file>",
"adjudication": "proposed",
"trust_tier": "machine-confirmed",
"title": "<the concept's own title>",
"title": "<the concept's own title, or the heading it stands under (point 10)>",
"own_title": "<the file's title, only where `title` was inherited>",
"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>",
"parent": { "concept_id": "<the concept enclosing this one>", "title": "<its title>" }
"parent": { "concept_id": "<the concept enclosing this one>", "title": "<its title>" },
"text_sha256": "<hex digest of `text`>",
"text": "<the concept body, or the passage of it that answers (point 8)>",
"passage": { "start": 8000, "end": 12000, "of": 35000 }
}
],
"withheld": [ { "concept_id": "<bundle-local id>", "rule": "<why it was cut>" } ]
"withheld": {
"total": 401,
"by_rule": { "below_k": 390, "no_lexical_match": 11 },
"nearest": [ { "concept_id": "<bundle-local id>", "rule": "below_k", "title": "<its title>" } ],
"complete": false
}
}
```
1. `len(excerpts)` MUST equal `denominators.delivered`, and `len(withheld)` MUST
equal `denominators.withheld`. The counts and the lists are two statements of
the same fact, and a payload where they disagree is refused.
1. `len(excerpts)` MUST equal `denominators.delivered`, and `withheld.total` MUST
equal `denominators.withheld`, with `withheld.by_rule` summing to it. The
counts and the lists are two statements of the same fact, and a payload where
they disagree is refused. `withheld.nearest` names the best-ranked drops and
is the whole withheld set only where `withheld.complete` is true.
2. `contract` MUST be present so a reader can tell which revision it is holding.
3. Every excerpt MUST carry a non-empty `title`. An excerpt a reader cannot name
is one an answer cannot cite, whatever its rank. This is a measurement, not a
@ -306,8 +321,45 @@ are permitted; the checker reads only the members this section names.
across corpora what was measured on one. Where a bar belongs is in the
consumer's own judgement or in a gate that publishes its sweep.
**One reading is carried, with its rule in the open (v1.1).** `absent_terms`
lists the question's words the bundle holds in NO form — not as written, and
not through a relative the pre-pass reads the word as — and `weak` is true
when nothing was delivered or `absent_terms` is not empty. That is not the
verdict falsified above: it asks whether a word exists in the bundle at all,
which does not move with question style or corpus size the way the two
shares did. A reader seeing `weak` rephrases in the bundle's own words, and
if it stays weak, says the bundle does not cover the question.
The checker does not read this member, for the same reason: it holds a
payload's FORM, and these lists carry no claim a form can be held to.
8. A pre-pass MAY deliver an excerpt of a large concept as the PASSAGE that
answers the question rather than the whole body. It then MUST say so, as
`passage: {start, end, of}` — whole numbers, `0 <= start < end <= of`,
character offsets of the passage in the concept's body and that body's
length — and `text_sha256` digests the delivered `text` while `sha256` stays
the concept file's, so the whole remains one fetch away by `concept_id`. The
delivered `text` MAY carry the nearest heading above the passage and markers
where text was left out, so its length is not `end - start`. The checker
refuses a `passage` that is not such a place (`passage_malformed`): a place
that is not a place sends a reader who fetches the concept to the wrong
characters of it.
9. A pre-pass MAY take several sub-questions in one run. Its payload then
carries `questions` — the list, in the order asked — in place of
`question`; every excerpt carries `subquestions`, the indices into
`questions` of the sub-questions it answered, the one whose text it carries
first; and `coverage` carries one block per sub-question under
`subquestions`, plus `weak_subquestions` and a `weak` that is true only when
every sub-question is weak. The cut is ONE: the same budget and the same `k`
one question gets, so asking several times in one run does not buy a larger
payload, and point 1's identities hold over the whole. The checker refuses
an excerpt whose `subquestions` are not distinct indices into `questions`,
or that carries them in a payload listing no `questions`
(`subquestions_unindexed`). A run of one question is the single form.
10. An excerpt whose concept's own title is a position rather than a name — a
table block a producer could only name by the line it starts on — MAY carry
as `title` the title of the concept it stands under in the same document,
and then MUST carry the file's own title as `own_title`, so the name shown
is never mistaken for the one in the file.
## 9. Prohibitions
@ -327,7 +379,10 @@ are permitted; the checker reads only the members this section names.
## 10. What this does not decide
- **No engine, ranker or cutter is designed here.** The contract binds a payload
and a document, not a retrieval algorithm.
and a document, not a retrieval algorithm. This library's pre-pass ranks by
BM25 over passages and titles by default and keeps its older three-signal
fusion reachable (`--ranking fusion`); a payload is conformant or not
whichever produced it.
- **No instrument is blessed.** § 7 requires that one be named and validated;
which one is the profile's choice.
- **Bundle shape is the producer's question.** Whether a corpus is nested, split