"""The guard after a repair: the pages without a home and the sources without a main page that the auditor reports in a repaired collection are asked of the model again, and its answer is applied. No model call, no network, no program started (CLAUDE.md rule 1). Order 35 A2b and B3.3 (the operator 22.10.2026, "Lag vakten som egen kommando (Anbefalt)", PLAN.md ยง Rammer point 10): the guard of kpack run-after, used as a library and not changed. Usage: python3 -m okfwiki.kguard ask --work DIR --bundle WIKI --sources DIR --out DIR python3 -m okfwiki.kguard apply --work DIR --asked FILE --answer FILE --bundle WIKI - ask runs the frozen auditor in this process (kpack.run_audit) on --bundle against --sources, leaves out the retired checks (kpack.RETIRED) and the findings the operator approved on his list (kpack.HOMELESS_APPROVED), and reads the pages without a home and the sources without a main page as kpack does (klink.homeless). With no finding it writes nothing and exits 0. A finding the guard cannot mend (a check outside klink.GUARDED) is named and stops: exit 5, and nothing is written. Otherwise it writes the guard's task to --out with klink.guard_parts, the catalogue being kpack.main_catalogue for the last pack of packs.json, and `asked.json` (okf-wiki/guard-asked/1: the pages, the sources, the catalogue, the pack, the parts, the answer path, the collection's sha256, krepair.tree_sha256, and the sha256 of accepted.json), and exits 4: run the home task. It never writes over a file that exists. - apply does with the answer what kpack.apply_guard does: klink.read_guard against the pages that cite each asked source (klink.guard_candidates), a main page per source in the source's place, a home per page with the source that brings the page (kpack.first_files), then kpack.drop_dangling, written with kpack.write_state. It logs in its own folder, WORK/K-guard/r35-/guard.json, instead of packs.json. It refuses an asked task already applied (`applied`) a --bundle that is not the collection asked (`stale-bundle`), and an accepted.json that changed since ask, as a krepair fix between ask and apply changes it without changing the bundle (`stale-accepted`): exit 1, nothing written. Exit 0 done; 1 refused, one line per reason `refused: `; 2 cannot run; 4 the task is written (run it); 5 STOP: a finding the guard cannot mend. """ from __future__ import annotations import argparse import json import sys import traceback from collections import Counter from pathlib import Path from typing import Any from okfwiki import klink, kpack, krepair from okfwiki.common import RunError ASKED_SCHEMA = "okf-wiki/guard-asked/1" LOG_SCHEMA = "okf-wiki/guard-log/1" LOG_PREFIX = "r35-" # WORK/K-guard/r35-/, one folder per applied answer (order 35 A2b) LABEL = "after the repair" EXIT_GUARD = kpack.EXIT_GUARD EXIT_BREACH = kpack.EXIT_BREACH def last_pack(work: Path) -> int: packs = [int(r["pack"]) for r in kpack.pack_log(work)["packs"]] if not packs: raise RunError(f"{kpack.k_work(work) / 'packs.json'} lists no pack") return max(packs) def accepted_sha256(work: Path) -> str: """The sha256 of WORK's accepted.json, or "" when there is none: the accepted state a guard task was asked on.""" path = kpack.k_work(work) / "accepted.json" return krepair.file_sha256(path) if path.is_file() else "" def cmd_ask(args: argparse.Namespace) -> int: work, bundle, sources, out = Path(args.work), Path(args.bundle), Path(args.sources), Path(args.out).resolve() kpack.check_pending(work) if out.exists() and any(out.iterdir()): raise RunError(f"{out} holds files already; the guard's task is never written over what exists") audit_doc = kpack.run_audit(bundle, sources) approved = kpack.read_approved(work) findings = [f for f in audit_doc["findings"] if isinstance(f, dict) and f.get("check") not in kpack.RETIRED and not kpack.is_approved(f, approved)] print(f"audit: {len(findings)} findings (" + (", ".join(f"{c} {k}" for c, k in sorted(Counter(str(f.get("check")) for f in findings).items())) or "none") + ")") if not findings: print("guard: no page without a home, no source without a main page; no task") return 0 cannot = [f for f in findings if f.get("check") not in klink.GUARDED] if cannot: print("STOP: a finding the guard cannot mend; the operator decides:") for f in cannot: print(f" {f.get('check')} {f.get('file') or ''}") return EXIT_BREACH pages, missing = klink.homeless({"findings": findings}) last = last_pack(work) catalogue = [str(e["id"]) for e in kpack.main_catalogue(kpack.read_index(work), kpack.read_accepted(work), last)] parts = klink.guard_parts(bundle, pages, missing, catalogue, LABEL) paths = [out / f"part-{i}.md" for i in range(1, len(parts) + 1)] answer = out / "answer.json" asked = {"schema": ASKED_SCHEMA, "bundle": str(bundle.resolve()), "bundle_sha256": krepair.tree_sha256(bundle), "accepted_sha256": accepted_sha256(work), "pack": last, "pages": pages, "sources": missing, "catalogue": catalogue, "parts": [str(p) for p in paths], "answer": str(answer)} out.mkdir(parents=True, exist_ok=True) for path, text in [*zip(paths, parts), (out / "asked.json", kpack.dump(asked))]: with path.open("x", encoding="utf-8") as fh: fh.write(text) print(f"guard: {len(pages)} pages without a home, {len(missing)} sources without a main page") for p in paths: print(f" part: {p}") print(f" answer: {answer}") return EXIT_GUARD def logs(work: Path) -> list[Path]: return sorted((work / "K-guard").glob(f"{LOG_PREFIX}*/guard.json")) def cmd_apply(args: argparse.Namespace) -> int: work, bundle, asked_path, answer = Path(args.work), Path(args.bundle), Path(args.asked), Path(args.answer) kpack.check_pending(work) asked: dict[str, Any] = kpack.read_json(asked_path) if asked.get("schema") != ASKED_SCHEMA: raise RunError(f"{asked_path} is not the guard's asked task ({ASKED_SCHEMA})") asked_sha = krepair.file_sha256(asked_path) refusals: list[krepair.Refusal] = [] for log in logs(work): if json.loads(log.read_text(encoding="utf-8")).get("asked_sha256") == asked_sha: refusals.append(krepair.Refusal("applied", f"{asked_path} (logged in {log})")) if krepair.tree_sha256(bundle) != asked["bundle_sha256"]: refusals.append(krepair.Refusal("stale-bundle", f"{bundle} is not the collection {asked_path} asked")) if accepted_sha256(work) != asked.get("accepted_sha256"): refusals.append(krepair.Refusal("stale-accepted", f"{kpack.k_work(work) / 'accepted.json'} changed since " f"{asked_path} was asked; ask again")) if refusals: return krepair.refuse(refusals) last = int(asked["pack"]) got = klink.read_guard(kpack.read_json(answer), asked["pages"], asked["sources"], asked["catalogue"], klink.guard_candidates(bundle, asked["sources"])) acc = kpack.read_accepted(work) for src, pid in got.main_pages: name = kpack.source_name(src) acc["main_pages"] = [m for m in acc["main_pages"] if m["source"] != name] + [ {"source": name, "concept_id": pid, "pack": last, "by": "guard"}] firsts = kpack.first_files(acc) for pid, hid in got.homes: if pid not in firsts: raise RunError(f"the guard homed {pid}, which has no accepted fragment") acc["homes"].append({"source": firsts[pid], "concept_id": pid, "home": hid, "pack": last, "by": "guard"}) dropped = kpack.drop_dangling(acc) answered = {"homes": len(got.homes), "main_pages": len(got.main_pages), "none": got.none, "unanswered": got.unanswered, "rejected": dict(sorted(got.rejected.items())), **kpack.nonzero(dropped=dropped[0] + dropped[1])} n = len(logs(work)) + 1 folder = work / "K-guard" / f"{LOG_PREFIX}{n}" if folder.exists(): raise RunError(f"{folder} exists; a guard log is never written over") entry = {"schema": LOG_SCHEMA, "at": krepair.now(), "asked": str(asked_path.resolve()), "asked_sha256": asked_sha, "answer": str(answer.resolve()), "answer_sha256": krepair.file_sha256(answer), "bundle_sha256": asked["bundle_sha256"], "pack": last, "answered": answered} kpack.write_state(work, f"guard-{LOG_PREFIX}{n}", {"accepted.json": acc}, {folder / "guard.json": kpack.dump(entry)}) print(f"guard answer: homes {len(got.homes)}, main pages {len(got.main_pages)}, none {len(got.none)}, " f"unanswered {len(got.unanswered)}, rejected {sum(got.rejected.values())} -> {folder / 'guard.json'}") kpack.print_dropped(*dropped) return 0 def build_parser() -> argparse.ArgumentParser: p = argparse.ArgumentParser(prog="python3 -m okfwiki.kguard", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) sub = p.add_subparsers(dest="command", required=True) a = sub.add_parser("ask") for name in ("--work", "--bundle", "--sources", "--out"): a.add_argument(name, required=True) y = sub.add_parser("apply") for name in ("--work", "--asked", "--answer", "--bundle"): y.add_argument(name, required=True) return p COMMANDS = {"ask": cmd_ask, "apply": cmd_apply} def main(argv: list[str] | None = None) -> int: args = build_parser().parse_args(argv) try: return COMMANDS[args.command](args) except (RunError, OSError, UnicodeDecodeError, json.JSONDecodeError) as exc: print(f"kguard cannot run: {exc}", file=sys.stderr) return 2 except Exception: # an input this code did not foresee: still "could not run", with the traceback traceback.print_exc() return 2 if __name__ == "__main__": sys.exit(main())