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>
188 lines
9.8 KiB
Python
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())
|