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

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

Browse source 
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>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-20 23:32:22 +02:00
commit e3169ec50c
15 changed files with 708 additions and 251 deletions
Download patch file Download diff file Expand all files Collapse all files

174
src/llm_ingestion_okf/consume.py
View file

@ -717,14 +717,14 @@ KNOWN_POSITIVE_CASE = "docs/consumption-contract.md, encoded as a JSON string"
#: `measure()`'s own answer for that file. Vacuous ALONE -- which is why the
#: delta below exists.
KNOWN_POSITIVE_EXPECTED = 16_389
KNOWN_POSITIVE_EXPECTED = 16_738
#: The second, independent route. `wc -c` reports 15 972 raw bytes for the same
#: The second, independent route. `wc -c` reports 16 316 raw bytes for the same
#: file; the difference is this file's JSON quoting and escaping overhead. A
#: reader can derive it without running `measure()` at all, and it moves the
#: moment `measure()` changes what it counts -- which is what stops
#: `expected == measured` from proving nothing.
KNOWN_POSITIVE_ENCODING_DELTA = 417
KNOWN_POSITIVE_ENCODING_DELTA = 422
#: The two places that file can be, resolved in this order.
#:
@ -2120,7 +2120,31 @@ def cut(
# --- The payload (SS 8) -------------------------------------------------------
#: SS 8.2: present so a reader can tell which revision it is holding.
CONTRACT_REVISION = "okf-consumption/1"
#:
#: **`/2` since 2026-09-20**, and the bump is the point of the field. `/1`'s
#: `withheld` was a FLAT LIST of every concept the cut dropped; `/2`'s is a
#: mapping carrying the total, the count per rule and the best-ranked near
#: misses by name. A consumer indexing the old key as a list would break, and
#: a revision string that did not move would let it break silently.
CONTRACT_REVISION = "okf-consumption/2"
#: How many near misses the payload names by default. The rest of the withheld
#: set is reported as COUNTS -- total and per rule -- which is what a
#: denominator is for; the near misses are what a reader can act on.
#:
#: **20, and the number is read off a measurement rather than chosen.**
#: Measured 2026-09-20 on a 2313-concept bundle of one project's own
#: documentation: the flat list held 2 305 entries = 186 440 B of compact JSON
#: = **65.5 % of the 284 850-byte file**, and not one of those bytes counted
#: against the budget the same payload reports (`spent` was 45 192). So a
#: reader was handed 239 658 bytes the budget line did not know about, in
#: order to learn 2 305 concept ids with nothing beside them -- the field
#: `--withheld-titles` existed to buy, and which was off because buying it for
#: 2 305 entries cost another 37.9 %. At twenty entries the title and the
#: document are free, and the list becomes the one thing it never was: a set
#: of names a reader can ask for. `k` is 8, so twenty is the cut plus the next
#: twelve; the whole list stays reachable behind one switch.
WITHHELD_NEAREST_DEFAULT = 20
#: `--k` caps the DELIVERED set. The budget is the gate; this is a second,
#: cheaper bound so a question matching half the corpus does not run a
@ -2202,6 +2226,60 @@ def unanswered_terms(
return [term for term in terms if term in remaining]
def withheld_block(
withheld: Sequence[tuple[str, str]],
ranked: Sequence[tuple[Concept, float, int]],
*,
titles_by_id: Mapping[str, str],
sources_by_id: Mapping[str, str],
nearest: int = WITHHELD_NEAREST_DEFAULT,
) -> dict[str, object]:
"""The withheld set as a reader can use it: counts, then names.
**The near misses are read off `ranked`, not off `withheld`.** `cut` sorts
its drops by id so the partition is comparable between runs; that order is
alphabetical and says nothing about which concept a reader might want
next. `ranked` is in fused-rank order, so walking it and keeping the
dropped ones gives the drops in the order the instrument itself put them.
`complete` is a fact about THIS block and not about the run: true exactly
when `nearest` holds every withheld concept. A checker cannot use
`excerpts` + `withheld` as the bundle's own denominator unless it is true,
and the field is how it tells.
"""
rules: dict[str, int] = {}
for _, rule in withheld:
rules[rule] = rules.get(rule, 0) + 1
by_rule = {rule: rules[rule] for rule in WITHHOLDING_RULES if rule in rules}
# A rule outside the closed set would be a vocabulary no consumer can be
# held to (SS 5.3). It is carried rather than dropped -- a count that
# vanished would break the identity below without saying why.
by_rule.update({rule: count for rule, count in sorted(rules.items()) if rule not in by_rule})
rule_of = dict(withheld)
dropped = set(rule_of)
entries: list[dict[str, object]] = []
for concept, _, _ in ranked:
if len(entries) >= nearest:
break
if concept.concept_id not in dropped:
continue
entry: dict[str, object] = {
"concept_id": concept.concept_id,
"rule": rule_of[concept.concept_id],
}
if titles_by_id.get(concept.concept_id):
entry["title"] = titles_by_id[concept.concept_id]
if sources_by_id.get(concept.concept_id):
entry["source_file"] = sources_by_id[concept.concept_id]
entries.append(entry)
return {
"total": len(withheld),
"by_rule": by_rule,
"nearest": entries,
"complete": len(entries) == len(withheld),
}
def build_payload(
bundle_root: Path,
*,
@ -2214,7 +2292,8 @@ def build_payload(
rarity_weight: bool = False,
tie_shared_rank: bool = DEFAULT_TIE_SHARED_RANK,
title_covered: bool = DEFAULT_TITLE_COVERED,
withheld_titles: bool = False,
withheld_nearest: int = WITHHELD_NEAREST_DEFAULT,
withheld_full: bool = False,
stem_prefix: bool = DEFAULT_STEM_PREFIX,
source_quota: int | None = DEFAULT_SOURCE_QUOTA,
follow_parent: bool = DEFAULT_FOLLOW_PARENT,
@ -2224,24 +2303,31 @@ def build_payload(
Pure with respect to the clock and the network: the same
`(bundle_root, question, k, limit, cost_vocabulary, reserve_top_rank,
rarity_weight, tie_shared_rank, title_covered, withheld_titles)` at the
same bytes returns
rarity_weight, tie_shared_rank, title_covered, withheld_nearest,
withheld_full)` at the same bytes returns
the same object, every time.
**`withheld_titles` (default off) names what was dropped.** A `withheld`
entry carries `concept_id` and `rule` and no title, so a reader told that
262 concepts were withheld cannot tell WHAT was withheld without reading
the bundle -- which SS 2.2 forbids. The title closes that.
**`withheld` is COUNTS plus NAMES, never the whole list.** See
`WITHHELD_NEAREST_DEFAULT` for the measurement: the flat list was 65.5 %
of one real payload and carried nothing a reader could act on. The mapping
states `total` (equal to `denominators.withheld`, so SS 5.2's identity is
unmoved), `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), and `complete` (whether `nearest` IS the
whole set -- so a reader can tell a truncated list from a short one).
OFF BY DEFAULT BY MEASUREMENT, not by taste. Measured 2026-09-08: on N500
the payload grows 41 364 -> 57 023 bytes (+37.9 %), and on the 629-concept
K2 bundle the bookkeeping -- everything that is not an excerpt -- grows to
**122 704 bytes, past the 120 000-byte limit itself**. The instantiated
skill publishes that breaking point as "~75 KB at 629 concepts, reached at
roughly 8 000 concepts"; on by default would make that sentence false and
would move every consumer's bytes for a field none of them asked for.
Whether the naming is worth the bookkeeping is the caller's call, and the
flag is how it stays one.
**`withheld_full` is the explicit switch that brings the whole list
back**, and `withheld_nearest` is the cap when it is not given. Nothing is
deleted: the bookkeeping is off the default path, not gone, and the
per-rule counts mean the default still answers every question the flat
list answered in aggregate.
`--withheld-titles` is retired by this change rather than kept beside it.
It existed to buy the one field the near misses now carry by default, and
it was off because buying that field for 2 305 entries cost another 37.9 %.
A flag whose only remaining effect would be to STRIP the title from a list
the caller explicitly asked for in full names no decision worth two shapes
for one list.
**`link_in_signal` defaults to `False` since K3-25 and carries no CLI
flag** -- see :func:`concept_scores`. It keeps the door's `Enclosing
@ -2339,6 +2425,7 @@ def build_payload(
# payload rather than about the algorithm that produced it.
raise ConsumeError(f"spent ({spent}) exceeds limit ({limit})", code="budget_exceeded")
question_terms = list(dict.fromkeys(normalise(question)))
nearest_cap = len(withheld) if withheld_full else max(withheld_nearest, 0)
return {
"contract": CONTRACT_REVISION,
"bundle": {
@ -2389,19 +2476,16 @@ def build_payload(
),
},
"excerpts": list(delivered),
# Emitted only under the flag, and then only where the concept carries
# a title, so a bundle whose concepts have none produces the same bytes
# either way. See this function's docstring for the measurement that
# keeps the default off.
"withheld": [
{"concept_id": concept_id, "rule": rule}
| (
{"title": titles_by_id[concept_id]}
if withheld_titles and titles_by_id.get(concept_id)
else {}
)
for concept_id, rule in withheld
],
# SS 5.1/5.2 on the NUMBERS and SS 5.3 on the names. See this
# function's docstring and `WITHHELD_NEAREST_DEFAULT` for why the flat
# list is not here.
"withheld": withheld_block(
withheld,
ranked,
titles_by_id=titles_by_id,
sources_by_id={concept.concept_id: concept.source_file for concept in concepts},
nearest=nearest_cap,
),
}
@ -2564,13 +2648,24 @@ def parse_args(argv: list[str] | None) -> argparse.Namespace:
help="The rule's explicit opt-out: `parent` is the pointer alone",
)
parser.add_argument(
"--withheld-titles",
"--withheld-nearest",
type=int,
default=WITHHELD_NEAREST_DEFAULT,
metavar="N",
help=(
"how many of the concepts that missed the cut the payload names, "
f"best-ranked first, with title and document. Default {WITHHELD_NEAREST_DEFAULT}. "
"The rest are reported as counts per rule; 0 names none"
),
)
parser.add_argument(
"--withheld-full",
action="store_true",
help=(
"give each withheld entry the concept's title, so a reader can see "
"WHAT was withheld without reading the bundle. OFF by default: it "
"grew a 270-concept payload by 37.9 %% and pushed a 629-concept "
"bundle's bookkeeping past the budget limit itself"
"name EVERY withheld concept instead of the nearest N. Measured "
"2026-09-20 on a 2313-concept bundle: the whole list is 186 440 B "
"= 65.5 %% of the written file, and none of it counts against the "
"budget the payload reports"
),
)
parser.add_argument("--out", type=Path, default=None, help="write here instead of stdout")
@ -2611,7 +2706,8 @@ def main(argv: list[str] | None = None) -> int:
title_covered=args.title_covered,
stem_prefix=args.stem_prefix,
source_quota=args.source_quota,
withheld_titles=args.withheld_titles,
withheld_nearest=args.withheld_nearest,
withheld_full=args.withheld_full,
follow_parent=args.follow_parent,
)
except ConsumeError as error:

166
src/llm_ingestion_okf/contract_check.py
View file

@ -109,12 +109,24 @@ class Report:
findings: tuple[Finding, ...]
rules_evaluated: int
excerpts_examined: int
#: The withheld entries this report READ, which since `okf-consumption/2`
#: is the sample the payload names and not the whole withheld set. The
#: total is in the payload; this is the denominator of what was checked,
#: and conflating the two would let a report claim it examined 2 305
#: entries it never saw.
withheld_examined: int
#: What the payload says its withheld set holds. `None` when it states no
#: total -- unmeasured, never zero.
withheld_total: int | None = None
def render(self) -> str:
named = (
f"{self.withheld_examined} withheld entries"
if self.withheld_total is None or self.withheld_total == self.withheld_examined
else f"{self.withheld_examined} of {self.withheld_total} withheld entries"
)
denominator = (
f"{self.rules_evaluated} rules over {self.excerpts_examined} excerpts "
f"and {self.withheld_examined} withheld entries"
f"{self.rules_evaluated} rules over {self.excerpts_examined} excerpts and {named}"
)
if not self.findings:
return f"conformant: {denominator}, 0 findings"
@ -311,12 +323,22 @@ def rule_excerpt_parent(ctx: Context) -> list[Finding]:
the resolved form: a `concept_id` and a `title`, naming a concept other
than the excerpt itself.
**The payload is its own denominator.** `excerpts` and `withheld` together
name every concept the pre-pass considered, which is every concept of the
bundle (SS 5.2), so a `parent.concept_id` in neither names nothing in the
bundle -- and the rule sees that without opening the bundle, the boundary
`rule_bundle_identity` keeps too. A payload lying about both lists at once
passes here and fails `denominator_identity` instead.
**The payload is its own denominator ONLY WHERE IT SAYS IT IS.** `excerpts`
and `withheld` together name every concept the pre-pass considered, which
is every concept of the bundle (SS 5.2) -- so a `parent.concept_id` in
neither names nothing in the bundle, and the rule sees that without
opening the bundle, the boundary `rule_bundle_identity` keeps too.
Since `okf-consumption/2` that premise is CONDITIONAL and the payload
states which it is: `withheld.nearest` is a sample of the drops unless
`withheld.complete` is true. Over a truncated block the clause is not run,
because every real parent pointing at a drop the sample did not name would
be refused -- a rule firing on the correct answer. It is stated rather than
silent: SS 8.6 says so, and the known-positive in the suite fires the
clause over a complete block on the same payload it is skipped on. The
other two clauses -- the shape, and a parent naming its own excerpt -- do
not read the denominator and run either way. A payload lying about both
lists at once passes here and fails `denominator_identity` instead.
**Conditional, like SS 8.4's fields.** An excerpt with no `parent` meets
this rule as it always did. `parent_unresolved` is not a finding: SPEC SS
@ -326,10 +348,14 @@ def rule_excerpt_parent(ctx: Context) -> list[Finding]:
if not ctx.payload_is_mapping:
return []
excerpts = [_mapping(raw) for raw in _sequence(ctx.payload.get("excerpts"))]
considered = {_text(excerpt.get("concept_id")) for excerpt in excerpts} | {
_text(_mapping(raw).get("concept_id")) for raw in _sequence(ctx.payload.get("withheld"))
}
considered.discard("")
block = _mapping(ctx.payload.get("withheld"))
complete = block.get("complete") is True
considered: set[str] | None = None
if complete:
considered = {_text(excerpt.get("concept_id")) for excerpt in excerpts} | {
_text(_mapping(raw).get("concept_id")) for raw in _sequence(block.get("nearest"))
}
considered.discard("")
findings = []
for position, excerpt in enumerate(excerpts):
if "parent" not in excerpt:
@ -340,7 +366,7 @@ def rule_excerpt_parent(ctx: Context) -> list[Finding]:
reason = "is not a `concept_id` and a `title`, so a reader can neither open nor cite it"
elif target == _text(excerpt.get("concept_id")):
reason = f"names the excerpt itself ({target!r})"
elif target not in considered:
elif considered is not None and target not in considered:
reason = (
f"names {target!r}, which is in neither `excerpts` nor `withheld` and so is "
"no concept of this bundle"
@ -420,41 +446,132 @@ def rule_denominator_identity(ctx: Context) -> list[Finding]:
def rule_denominator_lists(ctx: Context) -> list[Finding]:
"""SS 8.1: `delivered` against the excerpts, `withheld` against its TOTAL.
The two sides are not symmetric, and since `okf-consumption/2` they say so.
`excerpts` is the payload's product and its length is the count. `withheld`
is bookkeeping, and the flat list of it was 65.5 % of one measured payload
while answering nothing a reader could act on -- so the count it is held
against is the one the block states, not the length of the sample of near
misses it names. What keeps that honest is the next rule: the total is
decomposed over the closed rule set and the decomposition must add up.
"""
if not ctx.payload_is_mapping:
return []
counts = _mapping(ctx.payload.get("denominators"))
findings = []
for key, member in (("delivered", "excerpts"), ("withheld", "withheld")):
declared = _whole(counts.get(key))
if declared is None:
continue
actual = len(_sequence(ctx.payload.get(member)))
declared = _whole(counts.get("delivered"))
if declared is not None:
actual = len(_sequence(ctx.payload.get("excerpts")))
if declared != actual:
findings.append(
Finding(
"denominator_list_mismatch",
f"denominators.{key} is {declared} but {member} holds {actual}; "
f"denominators.delivered is {declared} but excerpts holds {actual}; "
"the count and the list are two statements of one fact (SS 8.1)",
)
)
declared = _whole(counts.get("withheld"))
block = _mapping(ctx.payload.get("withheld"))
total = _whole(block.get("total"))
if declared is not None and total is None:
findings.append(
Finding(
"denominator_list_mismatch",
"withheld reports no whole-number `total`; a bookkeeping block that "
"does not state its own count cannot be held against the "
"denominator (SS 8.1)",
)
)
elif declared is not None and total != declared:
findings.append(
Finding(
"denominator_list_mismatch",
f"denominators.withheld is {declared} but withheld.total is {total}; "
"the count and the block are two statements of one fact (SS 8.1)",
)
)
return findings
def rule_withheld_rules(ctx: Context) -> list[Finding]:
if not ctx.payload_is_mapping:
"""SS 5.3: every drop names the rule that dropped it -- in aggregate, and
by name for the ones the payload names.
Three statements have to hold together, or the truncation stops being a
sample and becomes a silence: `by_rule` adds up to `total` (so a reader
knows what KIND of drop the unnamed ones were), `nearest` is no longer
than `total`, and `complete` is true exactly when `nearest` IS the whole
set -- which is what `rule_excerpt_parent` reads before it treats the
payload as its own denominator.
"""
if not ctx.payload_is_mapping or "withheld" not in ctx.payload:
# A payload carrying no `withheld` at all is `denominator_identity`'s
# defect and `denominator_lists`' -- no rule here restates another.
# A `withheld` that is PRESENT and is not this block (the flat list of
# `okf-consumption/1`, say) falls through and is named below.
return []
block = _mapping(ctx.payload.get("withheld"))
findings = []
for position, raw in enumerate(_sequence(ctx.payload.get("withheld"))):
total = _whole(block.get("total"))
rules = _mapping(block.get("by_rule"))
counted = [_whole(value) for value in rules.values()]
if any(value is None for value in counted):
findings.append(
Finding(
"cut_undeclared",
"withheld.by_rule carries a count that is not a whole number; a "
"count that is not reported is unmeasured, not zero (SS 5.3)",
)
)
elif total is not None and sum(value for value in counted if value is not None) != total:
findings.append(
Finding(
"cut_undeclared",
f"withheld.by_rule sums to "
f"{sum(value for value in counted if value is not None)} but "
f"withheld.total is {total}; a decomposition that does not close "
"leaves drops with no rule at all (SS 5.3)",
)
)
nearest = _sequence(block.get("nearest"))
for position, raw in enumerate(nearest):
entry = _mapping(raw)
for key in ("concept_id", "rule"):
if not _text(entry.get(key)):
findings.append(
Finding(
"cut_undeclared",
f"withheld entry {position} carries no {key!r}; a visible "
"drop is worth more than a silent one (SS 5.3)",
f"withheld.nearest entry {position} carries no {key!r}; a "
"visible drop is worth more than a silent one (SS 5.3)",
)
)
if total is not None and len(nearest) > total:
findings.append(
Finding(
"cut_undeclared",
f"withheld.nearest names {len(nearest)} concepts but withheld.total "
f"is {total}; the sample cannot be larger than the set (SS 5.3)",
)
)
complete = block.get("complete")
if not isinstance(complete, bool):
findings.append(
Finding(
"cut_undeclared",
"withheld carries no boolean `complete`; without it a reader cannot "
"tell a truncated list from a short one (SS 5.3)",
)
)
elif total is not None and complete is not (len(nearest) == total):
findings.append(
Finding(
"cut_undeclared",
f"withheld.complete is {complete} while nearest holds {len(nearest)} "
f"of {total}; `complete` is a fact about the block, not a claim "
"about the run (SS 5.3)",
)
)
return findings
@ -608,7 +725,8 @@ def check(skill_text: str, payload: object) -> Report:
findings=tuple(findings),
rules_evaluated=len(RULES),
excerpts_examined=len(_sequence(ctx.payload.get("excerpts"))),
withheld_examined=len(_sequence(ctx.payload.get("withheld"))),
withheld_examined=len(_sequence(_mapping(ctx.payload.get("withheld")).get("nearest"))),
withheld_total=_whole(_mapping(ctx.payload.get("withheld")).get("total")),
)

83
src/llm_ingestion_okf/skill.py
View file

@ -373,15 +373,12 @@ def render(
budget = payload["budget"]
assert isinstance(budget, dict)
withheld = payload["withheld"]
assert isinstance(withheld, list)
assert isinstance(withheld, dict)
bookkeeping = okf_consume.measure(json.dumps(withheld, ensure_ascii=False))
per_withheld = bookkeeping / len(withheld) if withheld else 0.0
# `0` is what this was until 2026-09-20, and it was not a small number: it
# was the absence of a measurement printed as one. A bundle small enough to
# deliver everything withholds nothing, so there is no per-entry cost to
# extrapolate from -- and `int(LIMIT / 0.0)` was written as `0 concepts`,
# which reads as a bundle that breaks before it holds anything.
breaking = int(okf_consume.DEFAULT_LIMIT / per_withheld) if per_withheld else 0
withheld_total = withheld["total"]
assert isinstance(withheld_total, int)
named = withheld["nearest"]
assert isinstance(named, list)
name = f"{slug(bundle_id)}-consume"
text = template_path().read_text(encoding="utf-8")
@ -403,8 +400,8 @@ def render(
spent=int(budget["spent"]),
delivered=int(denominators["delivered"]),
bookkeeping=bookkeeping,
breaking=breaking,
withheld_count=len(withheld),
withheld_count=withheld_total,
withheld_named=len(named),
)
# Claude Code reads this header with a YAML reader, and `description`
# carries the root index's `bundle_id` raw -- a bundle this library did not
@ -454,8 +451,8 @@ def _rewrite(
spent: int,
delivered: int,
bookkeeping: int,
breaking: int,
withheld_count: int,
withheld_named: int,
) -> str:
replacements: list[tuple[str, str]] = [
(
@ -514,8 +511,8 @@ def _rewrite(
spent=spent,
delivered=delivered,
bookkeeping=bookkeeping,
breaking=breaking,
withheld_count=withheld_count,
withheld_named=withheld_named,
),
),
(
@ -580,8 +577,8 @@ def _scaling(
spent: int,
delivered: int,
bookkeeping: int,
breaking: int,
withheld_count: int,
withheld_named: int,
) -> str:
share = (spent / cost * 100) if cost else 0.0
return (
@ -593,43 +590,43 @@ def _scaling(
f"**{share:.1f} %** of the corpus. One question is one measurement: a\n"
"different question moves `spent` and this figure with it.\n\n"
+ _breaking_point(
total=total, bookkeeping=bookkeeping, breaking=breaking, withheld_count=withheld_count
total=total,
bookkeeping=bookkeeping,
withheld_count=withheld_count,
withheld_named=withheld_named,
)
)
def _breaking_point(*, total: int, bookkeeping: int, breaking: int, withheld_count: int) -> str:
"""The concept count at which the bookkeeping alone fills the budget.
def _breaking_point(
*, total: int, bookkeeping: int, withheld_count: int, withheld_named: int
) -> str:
"""What the payload costs beyond its excerpts, and whether it grows.
It is EXTRAPOLATED from the cost of one `withheld` entry, so a generation
run that withheld nothing has no slope to extrapolate from. That case used
to print `0 concepts` -- a division that never happened, rendered as a
measurement, and the one number in this document that said the bundle
breaks before it holds anything. The sentence is withheld instead, with the
reason and the two facts that are measured.
Until `okf-consumption/2` this section extrapolated a concept count at
which the bookkeeping alone would fill the budget, because `withheld`
carried one entry per considered concept and grew linearly. Measured
2026-09-20 on a 2313-concept bundle, that growth had arrived: the list was
186 440 B = 65.5 % of the written file, none of it counted against
`spent`.
It does not grow that way any more, so this section no longer states a
concept count -- a number extrapolated from a slope the code no longer has
would be a measurement of the previous revision. What it states instead is
the two facts that are measured on THIS bundle: what the bookkeeping cost
here, and that it is bounded by the near-miss cap rather than by the
bundle's size.
"""
if withheld_count == 0:
return (
"**The breaking point could not be measured on this bundle.** The\n"
"`withheld` list carries one entry per considered concept, and on this\n"
f"bundle at generation time nothing was withheld: all {total} concepts\n"
"were delivered. There is therefore no per-entry cost to extrapolate\n"
"from, and no concept count is stated here — a bundle large enough to\n"
"withhold something states one. What does hold either way: the\n"
"bookkeeping is not counted against `spent`, and the pre-pass reads\n"
"every concept body on every run, so growth is a wall-clock cost with\n"
"no precomputed index behind it."
)
return (
"**The breaking point, stated so it can be observed to have been passed.**\n"
"The `withheld` list carries one entry per considered concept and grows\n"
f"linearly: here it is **{bookkeeping} bytes** for {withheld_count} of\n"
f"{total} concepts. At roughly **{breaking} concepts** the bookkeeping alone\n"
f"reaches the {okf_consume.DEFAULT_LIMIT}-byte\n"
"limit, and although it is not counted against `spent`, a payload whose\n"
"bookkeeping dwarfs its content has stopped being a cut. The pre-pass also\n"
"reads every concept body on every run, so the same growth is a wall-clock\n"
"cost with no precomputed index behind it."
"**What the payload costs beyond its excerpts.** The `withheld` block is\n"
"counts plus names, not one entry per concept: here it is\n"
f"**{bookkeeping} bytes** — {withheld_count} withheld of {total} concepts,\n"
f"of which **{withheld_named}** are named. Its size is bounded by that cap\n"
"and by the number of distinct withholding rules, not by the bundle's size,\n"
"so it does not overtake the excerpts as a bundle grows; the whole list is\n"
"still reachable with `--withheld-full`, and then it does. None of it counts\n"
"against `spent`. The pre-pass reads every concept body on every run, so\n"
"growth is a wall-clock cost with no precomputed index behind it."
)