History

Kjell Tore Guttormsen e3169ec50c feat(consume): the withheld set is counts plus names, not one entry per concept Measured 2026-09-20 on a 2313-concept bundle of one project's own documentation: `withheld` held 2 305 entries = 186 440 B of compact JSON = 65.5 % of the 284 850-byte payload, and not one of those bytes counted against the budget the same payload reports (`spent` was 45 192). A reader was handed 239 658 bytes the budget line did not know about, to learn 2 305 concept ids with nothing beside them -- the title being exactly what `--withheld-titles` existed to buy, and which was off because buying it for 2 305 entries cost another 37.9 %. `withheld` is now a mapping: `total` (equal to `denominators.withheld`, so SS 5.2's identity is unmoved and closes on the NUMBERS), `by_rule` (the same total decomposed over the closed rule set, so "what kind of drop" is answerable without the list), `nearest` (the best-ranked drops BY NAME, with title and source document, so a reader who sees a near miss can ask for it) and `complete`. The near misses are read off the ranking, not off `cut`'s output: `cut` sorts by id so the partition is comparable, and that order says nothing about which concept a reader might want next. Same question, same bundle, after: 52 421 bytes, 18.4 % of the old file. The whole list stays reachable behind `--withheld-full`, and the two instruments that classify EVERY miss by its rule -- the retrieval gate and `okf_consume_measure` -- now ask for it explicitly and assert `complete` rather than assuming it. `--withheld-nearest N` sets the cap (default 20, which is `k` plus the next twelve). `--withheld-titles` is retired: a flag whose only remaining effect would be to STRIP the title from a list the caller asked for in full names no decision worth two shapes for one list. `CONTRACT_REVISION` moves to `okf-consumption/2`, because a consumer indexing the old key as a list would otherwise break silently. Three checker rules move with it, and one of them is the interesting case: `parent_unfollowable` used `excerpts` + `withheld` as the bundle's own denominator, which a truncated block is not -- so that clause now runs only where the payload SAYS it is complete, stated in SS 8.6 rather than left as a silence, with the other two clauses (shape, self-reference) running either way. `Report` carries both denominators, because a report claiming it examined 2 305 entries it never saw is the same defect one level up. The generated skill's "breaking point" section goes with it: it extrapolated a concept count from the cost of ONE withheld entry, and there is no such slope any more. It now states what this bundle's bookkeeping cost and that the block is bounded by the cap rather than by the bundle -- an extrapolation from a slope the code no longer has would be a measurement of the previous revision. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-09-20 23:32:22 +02:00
..
example-payload.json	feat(consume): the withheld set is counts plus names, not one entry per concept	2026-09-20 23:32:22 +02:00
README.md	feat(skills): a consumption-skill template with no defaults	2026-09-02 16:06:24 +02:00

Kjell Tore Guttormsen e3169ec50c feat(consume): the withheld set is counts plus names, not one entry per concept

Measured 2026-09-20 on a 2313-concept bundle of one project's own
documentation: `withheld` held 2 305 entries = 186 440 B of compact JSON =
**65.5 % of the 284 850-byte payload**, and not one of those bytes counted
against the budget the same payload reports (`spent` was 45 192). A reader was
handed 239 658 bytes the budget line did not know about, to learn 2 305 concept
ids with nothing beside them -- the title being exactly what `--withheld-titles`
existed to buy, and which was off because buying it for 2 305 entries cost
another 37.9 %.

`withheld` is now a mapping: `total` (equal to `denominators.withheld`, so
SS 5.2's identity is unmoved and closes on the NUMBERS), `by_rule` (the same
total decomposed over the closed rule set, so "what kind of drop" is answerable
without the list), `nearest` (the best-ranked drops BY NAME, with title and
source document, so a reader who sees a near miss can ask for it) and
`complete`. The near misses are read off the ranking, not off `cut`'s output:
`cut` sorts by id so the partition is comparable, and that order says nothing
about which concept a reader might want next.

Same question, same bundle, after: **52 421 bytes, 18.4 % of the old file**.
The whole list stays reachable behind `--withheld-full`, and the two
instruments that classify EVERY miss by its rule -- the retrieval gate and
`okf_consume_measure` -- now ask for it explicitly and assert `complete`
rather than assuming it. `--withheld-nearest N` sets the cap (default 20,
which is `k` plus the next twelve). `--withheld-titles` is retired: a flag
whose only remaining effect would be to STRIP the title from a list the caller
asked for in full names no decision worth two shapes for one list.

`CONTRACT_REVISION` moves to `okf-consumption/2`, because a consumer indexing
the old key as a list would otherwise break silently. Three checker rules move
with it, and one of them is the interesting case: `parent_unfollowable` used
`excerpts` + `withheld` as the bundle's own denominator, which a truncated
block is not -- so that clause now runs only where the payload SAYS it is
complete, stated in SS 8.6 rather than left as a silence, with the other two
clauses (shape, self-reference) running either way. `Report` carries both
denominators, because a report claiming it examined 2 305 entries it never saw
is the same defect one level up.

The generated skill's "breaking point" section goes with it: it extrapolated a
concept count from the cost of ONE withheld entry, and there is no such slope
any more. It now states what this bundle's bookkeeping cost and that the block
is bounded by the cap rather than by the bundle -- an extrapolation from a
slope the code no longer has would be a measurement of the previous revision.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-20 23:32:22 +02:00

example-payload.json

feat(consume): the withheld set is counts plus names, not one entry per concept

2026-09-20 23:32:22 +02:00

README.md

feat(skills): a consumption-skill template with no defaults

2026-09-02 16:06:24 +02:00

README.md

References for the consumption-skill template

Two files, and they play different roles.

example-payload.json — a conformant payload in the shape docs/consumption-contract.md § 8 fixes. It is the known-positive for tools/okf_contract_check.py: the suite checks that this file passes, so a checker that refuses everything cannot be green. Its three excerpts carry one of each adjudication value on purpose, so that the closed set is exercised rather than asserted. The digests are real sha256 digests of the paths beside them, not of any real concept file: the example is a shape, not a bundle.
SKILL.md beside this directory — the template a per-corpus skill copies.

Copying the template

Copy skills/okf-consume-template/ to wherever the per-corpus skill lives.
Replace every <PLACEHOLDER>. None has a default; a copy with one left is unfinished, not configured.
Keep every ## heading. The checker reads them by name.
Point --payload at your own pre-pass output, not at this example, and run the checker in the corpus repo's test suite rather than by hand.

The checker checks shape. The division of labour (§ 2) and the prohibitions (§ 9) are properties of a run, and no static check can see them.