okf-wiki/gates/REPAIR.md
Kjell Tore Guttormsen 0fd86a23a3
okf-wiki 1.1.1
First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:03:20 +01:00

134 lines
9.6 KiB
Markdown

# Repair gate
`repair_gate.py` is the judge of the repair command (`python3 -m okfwiki.krepair`, order 34, contracts K18 and K19).
It was written and run RED before the command existed (order 34, session A). It calls no model.
```
python3 gates/repair_gate.py --manifest gates/repair.manifest.json -- python3 -m okfwiki.krepair
```
The command after `--` is the program each case's arguments are appended to; it runs from the repository root.
Exit 0 GREEN (every case passed), 1 RED, 2 the gate could not run.
## What it builds
The gate builds its own collection from the fixtures in `gates/repair/`, with the frozen tools only: `kblocks order`
and `blocks`, `kpack skeleton`, `pack` and `accept` (two packs of three sources), `kassemble build --at
2026-01-01T00:00:00Z`, `klink accept` and `kassemble build --links`. No generated page is in git.
- `kilder/`: a K1 source root made by `okfwiki.sources freeze` from text written for the gate about beekeeping: three
docs pages (`docs-en-hive.md`, `docs-en-honey.md`, `docs-en-swarm.md`) and one release note
(`release-v2.1.0.md`). Nothing in it comes from any documentation (CLAUDE.md rule 3).
- `fragments/pack-1.json`, `pack-2.json`: the compiler's output for the two packs, written by hand: 19 fragments,
three main pages and five homes.
- `links.json`: the five links of the base, by page, sentence text, anchor and target.
- `agent.md`, `agent-shared.md`: the agent files the task cases give `--agent`; the second shares a run of eleven words
with a line of a source.
- `stubs/`: three commands that must each turn the gate RED (below).
The base has eight pages (`hive`, `frames`, `brood`, `smoker`, `water`, `honey-harvest`, `swarming`,
`queen-cells`), 20 claims and five links, and must come out with no auditor finding and criterion 1 at 20 of 20, or
the gate cannot run. It holds what the cases need: a fragment of two sentences, a merged fragment, two fragments with
context quotes, history from the release note, two fragments in two concepts that share one footnote, two equal
sentences on one page (the second linked), a page with one fragment and a link to it, a main page with one fragment
and a page whose home it is, and a main page that stands on history alone once its own source's fragment goes.
## What it measures
Every case runs in a fresh copy of the base. For each case, by the gate's own code and apart from the command's
report:
1. **Exit code and refusal codes.** Each step's exit code is the case's (0 done, 1 refused). The codes are read from
the lines `refused: <code> <claim or record>` on stdout or stderr; the set must be the case's, and a line that names
no claim or record fails. The codes are listed with their meaning in the manifest's `refusal_codes`.
2. **The pages.** A case that writes is built with `kassemble build --links --replace --at 2026-01-02T00:00:00Z`; the
concept pages whose bytes differ from the base (`index.md` and `log.md` left out; a page gone counts) must be
exactly the case's `pages_changed`, and the pages gone exactly its `pages_gone`.
3. **The claims.** The frozen `claims.extract` runs on both collections. The (id, `excerpt_sha256`) pairs that are
gone and those that are new must be, by id, exactly the claims the case names in `claims_before` and
`claims_after`; so every other claim keeps its id and its `excerpt_sha256`. Where a case gives `excerpts`, the
claim must show exactly those (file, line) excerpts in that order.
4. **The auditor and criterion 1.** The frozen auditor's findings on the result, as (check, file), are exactly the
case's `findings` (most cases: none), and criterion 1 is N of N with no claim left without a key.
5. **The links.** The links file after the build holds exactly the base records, without the case's `links_removed`
and with its `links_added` (page, sentence key, anchor, target), and every record's `at` points at its anchor in its
sentence on the built page.
6. **The command's diff.** After a `fix`, the gate runs `diff --old <base> --new <result> --sources --repairs
WORK/K-work/repairs.json --out DIR`: exit 0, `ids.json` (`{"ids": [...]}`, the form `claims calls --ids` reads)
must hold exactly the new and changed claim ids the gate measured, and `sider.json` (`{"pages": [...]}`) exactly
the changed pages.
7. **Nothing written on a refusal.** A refused step changes no file in the work folder, the links file, the collection
or the output folder (sha256 of each tree before and after). `task` and `linkset` change none of the first three.
No case may change the sources or the copy of the old collection.
`task` cases: every `<task>.parts.json` in the output folder is `{"parts": [paths], "answer": path}`; every part
exists and is at most `kpack.PART_CHARS` characters; no two tasks share an answer path; each listed fragment's
footnote stands in exactly one task, and that task holds the page title, every sentence of the fragment, its quote,
its context quote and lines of its block that the case names.
`linkset` cases: the output folder holds `group-<n>.sentences.json` (the `okf-wiki/link-sentences/1` form `klink task
--sentences` reads) and `group-<n>.catalogue` (one id per line) per group; the frozen `klink task` runs on each pair;
the sentences of all groups are exactly the candidates; and each candidate's catalogue holds its current target.
## Where the denominator comes from
Every page, sentence, link and finding a case expects is written by hand in `repair.manifest.json` from the sources in
`gates/repair/kilder/`: pages by name, claims as sentence text with its occurrence `n` on the page (counted from 0, as
klink counts), links as page, sentence text, anchor and target. The gate turns a sentence into its claim id with the
frozen `klink.key_text` (the first 16 hex characters of its sha256, plus `-<n>`), and a fragment into its footnote with
the frozen `kassemble.label`, from its file, span, quote and mark. Nothing is taken from the command.
The findings of the three removal cases follow from K2 as written: a main-topic source no page lists in `x-main-for`
is `main-page-missing`, and a page that is not a main page and has no link from one is `no-main-page-link`. When the
main page `swarming` goes, its source has no main page and `queen-cells`, whose home it was, has no link from a main
page; when `honey-harvest` loses its only fragment from `docs-en-honey.md`, kassemble writes no `x-main-for` (a main
page record counts only for a source the page cites), so the source has no main page and the page is no main page and
has no home.
## The formats the gate fixes
The command did not exist when the gate was written, so the gate fixes what K18 leaves open, and the command follows
it:
- Answers (`okf-wiki/repair-answers/1`): `{"schema", "answers": [{"concept_id", "footnote": "s…", "action": "replace",
"fragments": [{"text", "quote", "anchor": {"file", "start", "end"}, "provenance", "context"?}]} | {"concept_id",
"footnote", "action": "remove"}]}`.
- A repair list in K17's schema, rendered from the base: each claim with its id, `excerpt_sha256`, page, line, mark,
kind (`docs` or `notes`), its excerpts as `sources` (`kilde/<file>`, line), origin `o33` and its reasons; each link
candidate with the base record's `at`, origin `o33-kandidat`. `claims_sha256` is the sha256 of the base's claim list
(`claims list` output, given as `--claims`); `verdicts_sha256` is the sha256 of no bytes.
- `<task>.parts.json`, `group-<n>.sentences.json` and `group-<n>.catalogue`, `ids.json` and `sider.json` as above.
- Command arguments: `--page` and `--to` are page files (`hive.md`), `--sentence` a sentence key.
## The cases
32 cases: 20 that write (replace one with one and with two, a two-sentence fragment, a merged fragment, a release-note
fragment, context kept and context replaced, remove one, remove the last on a page and on a main page, remove the last
from a source on its main page, a shared footnote, equal sentences, a repair that makes a sentence equal to a later
one, a link whose anchor stays and one whose anchor goes, unlink, relink, two repairs in one file, identity), one task,
one linkset, and ten refusals (a quote not verbatim beside a good answer, a quote from another source, an unknown key,
a collection built before the last repair, two answers for one fragment, a stale list, an agent file that shares eight
words, a relink to a page that does not exist, an unlink with the wrong `at` and with the wrong anchor). Each case says
in `what` what it tries.
## The stubs and the gate's own test
`gates/tests/test_repair_gate.py` shows that each stub turns the gate RED with no case passed: `noop.py` (does
nothing, exit 0), `refuse_all.py` (`refused: x`, exit 1, writes nothing) and `touch_generated.py` (gives every page a
new `generated.at`; the rebuild keeps it, so the identity case sees every page changed). It also shows that a changed,
missing or extra fixture stops the gate (exit 2), that a missing command and a missing module are RED, and it tries
the checks a command cannot be run against yet with handmade outputs (task, linkset, a refusal, a link command).
```
python3 -m unittest discover -s gates/tests -p 'test_repair_gate.py'
```
## Not measured
- The command's `diff` after `unlink` and `relink`: K18 gives them no work folder, so they write no repairs log, and
the gate checks their pages, claims and links but not a diff.
- `linkset`'s refusal of a stale list: K18 gives it no `--claims`; its cases give a list with the hash of the base's
claim list.
- A fragment whose block alone is over `kpack.PART_CHARS` (task exit 2), and the instructions' own eight-word check:
the command's unit tests try them.
- The repairs log's content: only through the command's `diff`.