llm-ingestion-okf/docs/plan
Kjell Tore Guttormsen 01e4170fe4 docs(plan): make retrieval cost a first-order element of the consumption contract
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.
2026-08-25 23:38:34 +02:00
..
execution-order.md feat(guard): bump the pin to >=0.3,<0.4 and pin Door C's allow_reserved=False 2026-08-02 21:08:53 +02:00
mcp-bundle-population.md docs(mcp): Q2 gains upstream's tool surface as measured prior art 2026-07-27 20:16:47 +02:00
okf-2026-08-timestamp-tightening.md docs(upstream): move the OKF pin to canonical ad30107, re-record V-A8 2026-08-23 20:30:22 +02:00
okf-bundle-consumption-contract.md docs(plan): make retrieval cost a first-order element of the consumption contract 2026-08-25 23:38:34 +02:00
okf-v0.2-alignment.md docs(upstream): move the OKF pin to canonical ad30107, re-record V-A8 2026-08-23 20:30:22 +02:00
phase-1-door-a.md docs(plan): add detailed phase 1-4 implementation plans 2026-07-16 10:58:08 +02:00
phase-2-doors-b-c.md feat(guard): bump the pin to >=0.3,<0.4 and pin Door C's allow_reserved=False 2026-08-02 21:08:53 +02:00
phase-3-configurable-contract.md docs(okf-v0.2): the alignment track lands before the contract freezes 2026-07-26 11:42:37 +02:00
phase-4-node-half.md docs(phase-4): record linkedin-studio's two named requirements before the freeze 2026-07-25 20:34:54 +02:00