okf-wiki/okfwiki/kguard.py
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

188 lines
9.8 KiB
Python

"""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-<n>/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: <code> <what>`; 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-<n>/, 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())