Kjell Tore Guttormsen
2954216114
Funnet i review foer lukking:
1. Rapporten baar rotnivaaets tall, men ikke ordrens andre klausul ("read_dir
over stoerste katalog bundet"). Sveipet med den SHIPPEDE okf.directory_listing
over alle 478 nivaaer: verste nivaa noe sted er 6 073 tegn / 2 094 o200k-tok
(65 underkataloger) = 4,9 % av den flate formens 42 761. Det er dyrere enn
rota fordi hver sti er bundle-relativ - den maalte prisen paa at en sti er
brukbar ORDRETT i neste kall.
2. okf-konsum-kontrakter.md § 3.1 listet verktoeyene uten read_dir - samme
Fase-3-klasse som verktoeybeskrivelsene pkt. 2 flyttet.
3. CLAUDE.md-raden tidde om at bundle_id_notice har TO kallsteder mens
cost_baseline_notice har tre. Portefoelje-armen er BEVISST ikke wiret
(bundle_id_source er None der ved konstruksjon), og det staar naa uttalt i
stedet for aa vaere en asymmetri en leser maa gjette paa.
Sjekket ogsaa for annen prosa som beskriver den gamle to-trinns-stigen: eneste
gjenvaerende treff er docs/plan/2026-08-23-magentic-utforskningssloeyfe.md, et
DATERT plandokument som allerede beskriver read_bundle -> bundle_context (sant
til MAJOR-4 i oekt 77). Planer er historiske artefakter, ikke levende paastander
om flaten - ikke roert. Ingen treff under shared/ (pull-only subtree).
Ingen kodeendring.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
161 lines
9.1 KiB
Markdown
161 lines
9.1 KiB
Markdown
# OKF consumption contracts
|
||
|
||
> **This file is the source.** Three facts below span a producer
|
||
> ([`llm-ingestion-okf`](https://git.fromaitochitta.com/open/llm-ingestion-okf)) and this consumer,
|
||
> so neither side can hold the other to them from inside its own plan file. Docstrings, tests and
|
||
> the invariant ledger in `CLAUDE.md` point *here*; they do not restate the rule. A second copy of a
|
||
> contract is the drift this repository has a rule against.
|
||
>
|
||
> The producer's half is recorded in that repository's `docs/plan/office-intake.md` §§ 4–5 and
|
||
> `docs/consumption-contract.md`. Ratified at programme level 2026-09-02. Written in English because
|
||
> the counterparty half is, and a contract split across two languages is a contract nobody reads
|
||
> whole.
|
||
>
|
||
> Every number below comes from a command, and each command is written next to its number.
|
||
|
||
## § 1. The falsification threshold — `present` and not `unverified`
|
||
|
||
A falsification verdict may rest on a concept **only when both hold**:
|
||
|
||
```
|
||
evidence_for(path).state == "present" AND tier != "unverified"
|
||
```
|
||
|
||
Everything else is **reported and explicitly discounted**, never silently excluded. The report
|
||
carries the triple `(state, reason, items_seen)`: a concept that was dropped and a concept that was
|
||
read-and-discounted are different facts, and only the second is honest about what was actually read.
|
||
|
||
The threshold is expressed in **exactly one place** — `okf.admits_falsification(evidence) -> bool`.
|
||
A threshold spelled inline at each caller is a threshold nobody can find, and a second copy is free
|
||
to drift from the first.
|
||
|
||
**`author`, `usage_count` and `last_modified` are deliberately NOT required, and the denominator is
|
||
written down rather than implied.** SPEC § 5.1 names **six** keys on a `sources` entry — `resource`,
|
||
`id`, `title`, `author`, `usage_count`, `last_modified` — and the producer writes **two of them**:
|
||
|
||
```sh
|
||
# Grep-able anchor, never a line number — a line anchor into another repository's file rots
|
||
# on that repository's next edit, and this one has to survive being read from outside.
|
||
grep -A11 'Each `sources` entry:' ~/repos/_okf-canonical/SPEC.md # the six entry keys
|
||
grep -rh '^sources:' ~/repos/llm-ingestion-okf/examples/
|
||
# -> sources: [{ id: golden-v0-2-sales, resource: fixture }]
|
||
# (1 of the 26 markdown files under examples/ carries the key at all)
|
||
```
|
||
|
||
Measured 2026-09-02 against producer `62b6192`. **2 of 6, not 2 of 5** — an earlier draft of this
|
||
contract carried the smaller denominator, which would have understated how much of § 5.1 the
|
||
producer leaves unwritten. Requiring the three credibility signals would make the threshold
|
||
unreachable in practice while looking strict on paper: the worst of both. **The threshold names only
|
||
what is actually written.**
|
||
|
||
`usage_window` is a sibling of `sources`, not an entry key, and is outside the six.
|
||
|
||
## § 2. The adjudication state — absence is `unknown`, never `absent`
|
||
|
||
A concept carries its adjudication state in the frontmatter key **`adjudication`**, whose value set
|
||
is **closed**: `proposed` or `adjudicated`.
|
||
|
||
| Observation | State |
|
||
|---|---|
|
||
| `adjudication: proposed` | `proposed` |
|
||
| `adjudication: adjudicated` | `adjudicated` |
|
||
| the key is not present | **`unknown`** |
|
||
| any other value | **refused by name** — never mapped into the vocabulary |
|
||
|
||
**The third row is the whole contract.** A concept that does not carry the key means *we did not
|
||
learn whether this was adjudicated* (an older bundle), and collapsing that into `absent` — *it was
|
||
not adjudicated* — is a verdict on missing evidence presented as evidence of absence. It is the same
|
||
defect as collapsing `unreadable` into `absent` one layer up, and the same defect the ungiven-verdict
|
||
work removed from `RunResult.verdict`.
|
||
|
||
The fourth row is **validation, never repair**: an out-of-vocabulary value is an error, not an
|
||
extension point, and mapping it to `unknown` would silently invent the very state this contract
|
||
exists to keep honest.
|
||
|
||
**Honesty limit, stated:** this consumer's fixtures are **hand-written to the contract above**, not
|
||
produced by `llm-ingestion-okf`. Integration against the producer's own golden is later work and is
|
||
not claimed here.
|
||
|
||
## § 3. Identity across bundles — the pair `(bundle_id, concept_id)`
|
||
|
||
A concept ID is **bundle-local and stable**. Identity **across** bundles is the pair
|
||
**`(bundle_id, concept_id)`** — never the concept ID alone.
|
||
|
||
`bundle_id` resolves in a **fixed order**, and the resolved value carries **which source answered**:
|
||
|
||
| Order | Source | `origin` |
|
||
|---|---|---|
|
||
| 1 | the concept's own frontmatter | `declared-concept` |
|
||
| 2 | the bundle root's `index.md` | `declared-index` |
|
||
| 3 | neither declared it — the mount basename is used | `mount-derived` |
|
||
|
||
**Three origins, not a boolean.** A caller that cannot tell *"the concept said so"* from *"we fell
|
||
back twice"* has been handed a stamp it cannot audit.
|
||
|
||
**A base with no readable `index.md` is not "undeclared".** The existing navigation fail-fast
|
||
propagates unchanged; reading an unreadable base as *"no declaration"* is the tolerant-read defect
|
||
that widens an answer instead of refusing it. Only a base whose index *is* readable and declares
|
||
nothing falls through to the next row.
|
||
|
||
**Measured today: every base *in this repo* resolves `mount-derived`.** No shipped `index.md`
|
||
declares the key:
|
||
|
||
```sh
|
||
find shared -name index.md | wc -l # -> 7
|
||
grep -l 'bundle_id' $(find shared -name index.md) | wc -l # -> 0
|
||
```
|
||
|
||
So this contract changes which sources are **consulted**, not what happens when none of them
|
||
declares anything — which is why adopting it moves no existing call site.
|
||
|
||
### § 3.1. A declared id BEATS the mount; the mount is a filesystem accident
|
||
|
||
**Amended 2026-09-03 (S7a-3 pkt. 1), and the amendment is a consumer slacken.** Until then, a base
|
||
that declared an id its mount did not carry was **refused** (`BundleIdMismatch`) at every door. The
|
||
first delivered corpus that declares its own id — K2, measured 2026-09-03: 618 of 630 concept files
|
||
plus the root `index.md`, all saying `k2-trinn1-20260903`, delivered in a directory named
|
||
`K2-bundle-20260903` — could therefore **not be opened as delivered**. The only remedy was to
|
||
re-mount it under the declared name by hand, once per delivery, forever.
|
||
|
||
That is a consumer refusing a producer's legitimate output over a directory name. The rule is now:
|
||
|
||
- **The declared id is the identity.** The mount's basename answers only when nothing is declared.
|
||
- **A disagreement is RECORDED, never refused:** `ResolvedBundleId.mount` carries the overridden
|
||
directory, `ProvenanceStamp.bundle_id_source` / `DryRunReport.bundle_id_source` carry the whole
|
||
resolution into the artefacts, and the run prints **one warning line** naming both values.
|
||
- **A base is addressed by its declared id at BOTH doors.** The exploration catalogue
|
||
(`list_bundles` / `read_bundle` / `read_dir` / `read_file` / `quick_validate`) and the mandate
|
||
dispatcher resolve the same id. This is a consequence of the slacken rather than a separate decision: while
|
||
a disagreeing declaration was refused the two could not differ, and if they differed now, an
|
||
exploration's own minted mandate would be unroutable.
|
||
|
||
**What still refuses, because no mount name can settle it:** two **concepts inside one base**
|
||
declaring **different** ids. Such a base cannot say what it is, and an artefact stamped from it
|
||
would name one of two corpora at random. The check runs at every door that OPENS a base.
|
||
|
||
**The root `index.md` is NOT part of that agreement check** — decision B1 applied a second time.
|
||
Concept-beats-index is a *precedence* rule, so an index out of step with its concepts is the
|
||
fallback losing, not a collision; folding the index in would newly refuse exactly the K2-shaped
|
||
bases this amendment exists to admit.
|
||
|
||
**Honesty limits, stated.** (1) Without a named concept the root `index.md` answers, so a base whose
|
||
index declares X while its concepts declare Y resolves to X — that is B1's resolution order,
|
||
unchanged. (2) Two *differently named* directories that both declare the same id now collide in the
|
||
dispatcher's "two knowledge bases share the id" refusal; that branch used to require two mounts with
|
||
the same basename and is no longer defensive.
|
||
|
||
**There is no cross-bundle link form.** A consumer holding several bundles partitions per bundle;
|
||
the producer emits no syntax for pointing from inside one bundle into another, and adding one is out
|
||
of scope until a consumer states the need.
|
||
|
||
## § 4. What these three do not settle
|
||
|
||
- **The wire form of `sources` is the producer's to fix.** Flow-sequence-of-mappings is the normative
|
||
emission form; block form remains conformant OKF but outside the accepted subset. A known defect
|
||
stands on the producer side: `llm-ingestion-guard` 1.2.0 rejects a flow sequence of mappings for
|
||
`sources`. That is a **known producer-side gate defect, not a consumer error**, and this consumer
|
||
does not wait on it.
|
||
- **The trust tiers themselves** (§ 5.3 of the SPEC) are inferred, never stored — no credibility
|
||
score is written by either side.
|
||
- **Nothing here wires a library primitive into a run's stdout.** The reader reads; the caller
|
||
decides. Both halves of that split predate these contracts and are unchanged by them.
|