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

docs(plan): make retrieval cost a first-order element of the consumption contract

Browse source 
Second order 20260825T133057Z-193098605-from-.claude, carrying an operator
directive that how an agent finds information in a bundle must be
token-efficient, as a property the contract carries rather than a later
optimisation. The order prescribed the goal, left the form to us, and invited
the objection that "token-efficiency" is the wrong abstraction for a generic
layer. It is, so the element is not called that.

C6 — retrieval cost is declared: instrument, budget, denominator, breaking
point. It binds the READING side (the order's property 1): a conformant
consumption skill states the bound its cut targets, what a typical answer costs
against the whole-bundle denominator by a named instrument, which way cost
scales, and the corpus size at which its strategy stops fitting its budget.
Each is re-runnable as a command (property 2), and the instrument must
reproduce known-good figures before its own are believed — C3's second
corollary applied to a positive quantity.

Why not "token efficiency": a token is one encoder family's unit and fixing it
would adopt one vendor's arithmetic as everyone's (the move §3 already refuses);
"efficient" is a comparative with the denominator missing; and efficiency is a
property of a run while a contract binds a document. Reading a whole bundle
stays legal — doing it UNDECLARED does not.

Measured for this revision, all against stated refs: the gap was real (one
pre-revision hit, on an unrelated sense of "costs"); the cited 250 785 /
430 144 / 112 116 figures and their prior validation against three known-good
values hold; the reading model navigates rather than searches. A fifth
measurement the order did not know, prompted by vegnormal-okf's coord message:
IndexPolicy.per_directory is a JUDGING field (required_indexes/violations) —
no code path here emits a nested index, and materialize refuses STRICT_V1 for
exactly that reason. So a permitted shape is not an emitted shape, and §2 now
says a cost figure inherits the ref rather than the profile.

Bundle SHAPE stays with the repo that produces it (O2); no instrument is
blessed; no engine, ranker or cutter is designed. No src/, no bump, no tag.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-25 23:38:34 +02:00
commit 01e4170fe4
1 changed files with 169 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

176
docs/plan/okf-bundle-consumption-contract.md
View file

@ -14,6 +14,14 @@ than by constants* in this repo (README, "Upstream OKF versions"). A consumption
contract that did not share profile identity with the production side would
drift from it.
**Second order, 2026-08-25** (`20260825T133057Z-193098605-from-.claude`), carrying
an operator directive verbatim: how an AI agent finds relevant information in a
bundle must be token-efficient, and this is a property the contract carries
rather than an optimisation that can arrive later. That order prescribed the
goal and left the form to us, including the invitation to say so if
"token-efficiency" is the wrong abstraction for a generic layer. It is, for
three reasons; C6 is the property that was built instead.
This repo does not own any *bundle*. It owns the contract both sides of a bundle
are held to. That distinction is the whole of §2.
@ -62,6 +70,33 @@ moving from provisional to settled). `G.13` *approved* a **sixth** as a separate
item, for a case defined by being outside the bundle. The upstream record
already splits along the seam this document draws.
### 0.1 What was measured for the second revision
The second order supplied four claims and asked, as the first did, that they be
re-measured. All four hold; a fifth thing was measured that the order did not
know, and it changes §2.
Every measurement in this table was taken against this document at `d205b70`,
before the revision it prompted. The ref is stated because C2 requires it and
because the first row is a claim about a file the same commit then changed:
re-running that `grep` at HEAD now returns dozens of hits, and without the ref
the row would read as false rather than as superseded.
| Claim in the order | Command | Verdict |
|---|---|---|
| This document says nothing about what a read costs | `grep -in 'token\|kostnad\|cost\|budget\|effektiv\|context window\|kontekstvindu'` over the file, exit 0 | **holds** — one hit, l. 245, on an unrelated sense of "costs" |
| A consuming repo measured one imported base at 250 785 tokens, three bases at 430 144, and one listing call at 112 116 | the measurement document at the named commit, read read-only | **holds** |
| That instrument was validated against three known-good figures before its own numbers were consumed | same document | **holds** — and it is C3's second corollary applied to a positive quantity |
| The reading model navigates rather than searches: start at the index, follow the links, read each file whole | the reading-model analysis §9.1, quoted | **holds** |
The fifth measurement was prompted by a coordination message from the producing
repo, which reported the flat-index consequence from its own side and asked a
contract question about `IndexPolicy.per_directory`. Its three claims about this
library's source were checked line by line and all three hold. What the message
could not see is that `per_directory` is a **judging** field rather than an
emitting one, which is recorded in §2 because it changes what a consumption
profile may assume.
---
## 1. What the generic contract consists of
@ -70,8 +105,9 @@ Bundle-independent means: true of any OKF bundle, whatever its types, depth,
index shape or subject. Anything that needs to name a type, a frontmatter key or
a directory is not in this layer — it is in a consumption profile (§2).
Five elements. Four are the order's; the fifth was found in the sources it sent
us to read first, and is marked as an addition.
Six elements. Four are the first order's; the fifth was found in the sources it
sent us to read first; the sixth arrived on a second order and is marked, along
with the name it did not keep.
### C1 — Source marking on every claim
@ -137,6 +173,84 @@ enumerates its conditionally-written fields and states, for each, what absence
does and does not mean. Without that enumeration, an agent has no way to tell a
conditional field from an unconditional one, and the failure is silent.
### C6 — Retrieval cost is declared: instrument, budget, denominator, breaking point (second order)
*Beyond the first order's four and the addition above. The operator directive
this element carries used the words "token-efficient"; the element does not,
and the reasons are the first thing it has to say.*
**Why not "token efficiency".** Three objections, each one this document already
runs on elsewhere:
- **A token is one encoder family's unit.** One vendor's encoding is not what
another vendor's reader counts, and a generic contract that fixed the unit
would adopt one vendor's arithmetic as everyone's — the same move §3 refuses
when it declines to adopt one consumer's marking set as the required set. What
survives the vendor is *a named instrument and a stated number*, never the
instrument's name.
- **"Efficient" is a comparative with the denominator missing.** Efficient
against what? C3 exists because a claim whose scope is unstated is not a
measurement; an unanchored efficiency claim is that same failure with the sign
flipped, and it is harder to catch because it sounds like good news.
- **Efficiency is a property of a run; a contract binds a document.** No
contract can oblige a skill to be cheap. It can oblige the skill to state what
its read cost, so that expense is visible instead of silent — which is the
precondition for anyone making it cheap, and the thing whose absence is the
actual defect.
**The property, stated.** The cost of answering a question should track the
**question**, not the **corpus**. A retrieval strategy whose cost is the same
whatever is asked has not cut anything; it has deferred the whole corpus into
every run.
This is not a prohibition on reading a whole bundle. For a small corpus, reading
everything is the cheapest correct strategy, and a rule forbidding it would be
wrong. What the contract forbids is doing so **undeclared**. The obligation is
therefore the same shape as C4's: the cut must be declared, and C6 is the half
of that declaration which carries a number.
**What a conformant consumption skill declares.** Three things, none of which
requires a particular unit, engine or bundle shape:
1. **A budget and the instrument that measures against it.** The bounded context
the cut targets, as a number, in a unit named together with the tool that
produced it. "Bounded" without a bound is C3's failure in prose.
2. **The cost of the cut against the whole-bundle denominator.** What a typical
answer costs to assemble, and what reading the entire bundle at that ref
would cost, by the same instrument. The fraction held back is what makes
`[unread]` (C1, C4) a quantity rather than a gesture.
3. **Which way its cost scales, and the breaking point.** Whether cost tracks
the question or the corpus, and — stated as a number — the corpus size at
which the declared strategy stops fitting the declared budget. A strategy
with no stated breaking point cannot be observed to have passed it.
**The instrument is validated before its numbers are believed.** C3's second
corollary — a query is shown capable of finding before its negative result is
consumed — transfers unchanged to a positive quantity: a cost instrument
reproduces known-good figures before its own are used. This is not a
hypothetical discipline. The measurement that prompted this element did exactly
that, reproducing three published reference figures exactly before any new
number was consumed, and it is cited here as **form**, never as authority.
**The failure this exists to prevent, measured.** A corpus of three imported
bases was measured at 430 144 tokens in one encoding, one base alone at 250 785
— which is more than a 128k-context reader can hold at all — and a single
listing call at 112 116. None of those numbers was wrong, hidden or anyone's
bug. They were simply **never stated**, because nothing in any contract required
them to be, and the reading model in play reads every linked file whole, so a
flat index of several hundred links is several hundred whole files in every run.
The cost was a fact about the corpus long before it was a finding, and it became
a finding only because somebody happened to measure it.
**What this element does not reach.** C6 binds the **reading** side: what an
agent must be able to say about its own retrieval. Whether a bundle is *shaped*
so that a cheap cut is available — nested indexes, branch granularity, section
splitting — is the producer's question, is being decided under a separate order
in the repo that owns that corpus, and is deliberately not decided here. The two
halves meet at the ref (C2): the producer changes the shape, and the consumption
profile's cost figures are re-measured against the new ref rather than carried
forward.
---
## 2. How this relates to the profile mechanism we already own
@ -185,6 +299,32 @@ agent enumerates a directory only where the named profile says the index is
derived.** Where the index is authored, the directory is not the index's
denominator and a listing is not a check.
That rule was written as a correctness rule — a listing is not a check where the
index is authored. It is **also** a cost rule, because it bounds what the agent
reads, and naming both readings is what keeps it from being discarded as
pedantry by someone optimising (C6).
**A second binding, measured for this revision, and it cuts against the
optimistic reading.** `IndexPolicy` also carries `per_directory` — "an index at
every level, or only at the bundle root" — off by default. It is a **judging**
field: it is read by `required_indexes` and `violations`, which tell a caller
what to require and what to flag. No code path in this library *emits* a nested
index. The materializer refuses `STRICT_V1` for exactly this reason, in its own
words: that profile "sets `per_directory` and `entries_match_directory`, neither
of which this materializer honours". The external-bundle door writes one root
index and flattens each merged concept into the root namespace.
Two consequences for a consumption profile:
- **A permitted shape is not an emitted shape.** That a named profile allows
nesting says nothing about whether the bundle in front of the agent has any.
"This bundle is nested" is a structural claim and must be re-derived by
command against the ref, never read off the profile's field list — which is
the third bullet above, in the one case where the temptation is strongest.
- **A cost figure inherits the ref, not the profile.** Because shape can change
without the profile changing, a consumption profile's C6 numbers are anchored
to the ref they were measured at, and go stale when it moves.
This is the same rule Phase 3 already runs on, one level up: **a profile names
the key, a caller owns the value.** Here: the generic contract names the
required marking set; a consumption profile declares its extensions.
@ -262,7 +402,9 @@ with no extension and an explicit statement of why the sixth does not transfer.
## 4. What a bundle-specific consumption skill must deliver to be conformant
A checklist, not a design. Each item is checkable by reading the skill.
A checklist, not a design. Each item is checkable by reading the skill — and
items 2, 7 and 8 are checkable by re-running the command the skill states, which
is the point of requiring a command rather than a claim.
1. **Names its production profile and bundle ref.** Which profile the bundle is
built under, and the ref the profile's structural claims were measured
@ -282,9 +424,17 @@ A checklist, not a design. Each item is checkable by reading the skill.
6. **Draws the cut boundary explicitly**: what the deterministic part reads,
ranks and cuts; what the agent is forbidden to go fetch; and how the cut is
surfaced in output as `[unread]` rather than passing silently (C4).
7. **Enumerates a directory only where the named profile says the index is
derived** (§2).
8. **Carries its own quality claim honestly.** If no run has been scored against
7. **Declares a retrieval budget and names the instrument.** The bound the cut
targets, as a number in a stated unit, with the tool that measures it and the
known-good figures that tool was shown to reproduce first (C6).
8. **States its cost against the whole-bundle denominator, and its breaking
point.** What a typical answer costs to assemble, what the whole bundle at
that ref would cost by the same instrument, whether cost tracks the question
or the corpus, and the corpus size at which the strategy stops fitting the
budget (C6). A skill that cannot state these has not measured its own cut.
9. **Enumerates a directory only where the named profile says the index is
derived** (§2) — a correctness rule and a cost rule at once.
10. **Carries its own quality claim honestly.** If no run has been scored against
its checklist, it says so. The one implemented precedent we have is
explicitly unmeasured by its own admission, and was used here as a model for
*form*, never as evidence that the form works.
@ -305,4 +455,16 @@ A checklist, not a design. Each item is checkable by reading the skill.
owner does not carry it. Reported, not edited (O2).
- **`.claude`'s premise correction** (§0) is owed back as a coord message: the
ratification exists in the source repo; the query that found it absent was
scoped to 16 of 639 files.
scoped to 16 of 639 files. *(Sent; the correction is accepted and recorded
upstream.)*
- **Bundle shape is not decided here.** C6 binds what a reading agent must be
able to say about its retrieval. Whether a corpus is nested, split or
branched so that a cheap cut exists at all belongs to the repo that produces
it, and is under a separate order there. Deciding it from here would be O2.
- **No instrument is named, shipped or blessed.** C6 requires that a skill name
the instrument it used and show it reproducing known-good figures. Which tool
that is stays the skill's choice, because the unit is vendor-specific and
fixing one would be the mistake C6's first paragraph refuses.
- **No cost engine, ranker or cutter is designed here**, in either runtime. C6
is a disclosure obligation on a document, not a retrieval algorithm, and
nothing about how to *achieve* a cheap cut follows from it.