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

9.6 KiB

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.