onetrace-explain 0.1.0__tar.gz

onetrace_explain-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include _reproducible_sdist.py

onetrace_explain-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: onetrace-explain
+Version: 0.1.0
+Summary: A suggested explanation of a onetrace comparison: AI-generated, checked against the record, never a verdict
+Author-email: Shamik Saha <shamik.saha.rcciit@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Issues, https://github.com/shamiksaharcciit-oss/onetrace-issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: onetrace<0.5,>=0.4
+
+# onetrace-explain
+
+A suggested explanation of a onetrace comparison: **AI-generated, may be wrong**, and checked
+against the record before anyone reads it. Never a verdict: onetrace's verdicts and exit codes are
+what they are without it, and its exit codes say nothing about the runs. Don't use it as a CI gate.
+
+```
+onetrace localize runs/a runs/b --for answer --out report
+onetrace-explain report --dry-run          # the packet exactly as it would be sent; nothing sent
+onetrace-explain report --model anthropic:<model name>
+```
+
+- **What is sent:** a packet built from the report and the two runs' receipts: verdicts, stage
+  names and edges, outcome classes, digests and sizes, instrument names and versions, and the
+  constants that differ with both values (`--redact NAME` sends a name and digest only). Kept text
+  only with `--include-text`. A constant's value goes as the run recorded it, a path or a token
+  included; `--redact NAME` keeps it out. Never this machine's own paths, an environment variable,
+  the model key, a signing key or an anchor's proof. The first send of a kind of item to an endpoint asks first (`--yes` for scripts).
+- **The model:** yours, named in `~/.config/onetrace/explain.toml`:
+
+  ```toml
+  [model]
+  provider = "anthropic"          # or "openai" (any OpenAI-compatible endpoint, local ones too)
+  name = "<model name>"
+  key_env = "ANTHROPIC_API_KEY"   # the variable holding the key; the key is never written anywhere
+  # base_url = "http://localhost:8000/v1"   # for an openai-compatible server
+  ```
+- **The post-check,** with no model: a claim is dropped when it cites nothing, cites what the packet
+  doesn't hold, quotes a value its cites don't hold, or says what caused a difference. What's shown
+  says how many were dropped, and why.
+- **Checks, not conclusions:** each suggestion comes with onetrace commands to run. A lead is
+  confirmed or ruled out only by what those report.
+- **Recorded:** every explanation is a onetrace run of its own, under `<out>/explain/<run id>/`,
+  which `onetrace-verify` checks like any run.

onetrace_explain-0.1.0/README.md

@@ -0,0 +1,34 @@
+# onetrace-explain
+
+A suggested explanation of a onetrace comparison: **AI-generated, may be wrong**, and checked
+against the record before anyone reads it. Never a verdict: onetrace's verdicts and exit codes are
+what they are without it, and its exit codes say nothing about the runs. Don't use it as a CI gate.
+
+```
+onetrace localize runs/a runs/b --for answer --out report
+onetrace-explain report --dry-run          # the packet exactly as it would be sent; nothing sent
+onetrace-explain report --model anthropic:<model name>
+```
+
+- **What is sent:** a packet built from the report and the two runs' receipts: verdicts, stage
+  names and edges, outcome classes, digests and sizes, instrument names and versions, and the
+  constants that differ with both values (`--redact NAME` sends a name and digest only). Kept text
+  only with `--include-text`. A constant's value goes as the run recorded it, a path or a token
+  included; `--redact NAME` keeps it out. Never this machine's own paths, an environment variable,
+  the model key, a signing key or an anchor's proof. The first send of a kind of item to an endpoint asks first (`--yes` for scripts).
+- **The model:** yours, named in `~/.config/onetrace/explain.toml`:
+
+  ```toml
+  [model]
+  provider = "anthropic"          # or "openai" (any OpenAI-compatible endpoint, local ones too)
+  name = "<model name>"
+  key_env = "ANTHROPIC_API_KEY"   # the variable holding the key; the key is never written anywhere
+  # base_url = "http://localhost:8000/v1"   # for an openai-compatible server
+  ```
+- **The post-check,** with no model: a claim is dropped when it cites nothing, cites what the packet
+  doesn't hold, quotes a value its cites don't hold, or says what caused a difference. What's shown
+  says how many were dropped, and why.
+- **Checks, not conclusions:** each suggestion comes with onetrace commands to run. A lead is
+  confirmed or ruled out only by what those report.
+- **Recorded:** every explanation is a onetrace run of its own, under `<out>/explain/<run id>/`,
+  which `onetrace-verify` checks like any run.

onetrace_explain-0.1.0/_reproducible_sdist.py

@@ -0,0 +1,61 @@
+"""The build backend: setuptools' own (setuptools.build_meta), with its sdist archived so that two
+builds of the same tree are the same bytes. Wheels are built exactly as setuptools builds them.
+
+setuptools writes each sdist member with the file's mtime and owner, and the gzip header with the
+build clock, so two builds of one tree differ in those bytes alone. Here the release tree setuptools
+has already made is archived in sorted order, every member's time set to SOURCE_DATE_EPOCH (0 when it
+is unset), owner and group 0 with no names, modes normalised (0644 for files, 0755 for directories
+and executables), and the gzip header's time set the same way. The members and their contents are
+setuptools' own. It runs inside the build, before the archive exists; nothing is repacked afterwards.
+"""
+import gzip
+import os
+import tarfile
+
+from setuptools.command import sdist as _sdist_module
+
+
+def _epoch() -> int:
+    v = os.environ.get("SOURCE_DATE_EPOCH", "")
+    return int(v) if v.isdigit() else 0
+
+
+_setuptools_make_archive = _sdist_module.sdist.make_archive
+
+
+def _make_archive(self, base_name, format, root_dir=None, base_dir=None, owner=None, group=None):
+    if format != "gztar":
+        return _setuptools_make_archive(self, base_name, format, root_dir, base_dir, owner, group)
+    when = _epoch()
+    root = os.path.abspath(root_dir or os.curdir)
+    top = base_dir or os.curdir
+    paths = []
+    for d, dirs, files in os.walk(os.path.join(root, top)):
+        dirs.sort()
+        rel_d = os.path.relpath(d, root)
+        paths.append(rel_d)
+        paths.extend(os.path.join(rel_d, f) for f in sorted(files))
+    target = os.path.abspath(base_name + ".tar.gz")
+
+    def norm(ti):
+        ti.mtime = when
+        ti.uid = ti.gid = 0
+        ti.uname = ti.gname = ""
+        if ti.isdir():
+            ti.mode = 0o755
+        elif ti.isfile():
+            ti.mode = 0o755 if ti.mode & 0o111 else 0o644
+        return ti
+
+    with open(target, "wb") as raw, \
+            gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=when, compresslevel=9) as gz, \
+            tarfile.open(fileobj=gz, mode="w", format=tarfile.PAX_FORMAT) as tar:
+        for rel in paths:
+            tar.add(os.path.join(root, rel), arcname=os.path.normpath(rel), recursive=False, filter=norm)
+    return target
+
+
+_sdist_module.sdist.make_archive = _make_archive
+
+from setuptools.build_meta import *  # noqa: E402,F401,F403  -- the hooks, unchanged
+from setuptools.build_meta import __all__  # noqa: E402,F401

onetrace_explain-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+# setuptools' own backend, with its sdist archived reproducibly (_reproducible_sdist.py says how).
+build-backend = "_reproducible_sdist"
+backend-path = ["."]
+
+[project]
+name = "onetrace-explain"
+version = "0.1.0"
+description = "A suggested explanation of a onetrace comparison: AI-generated, checked against the record, never a verdict"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["onetrace>=0.4,<0.5"]
+license = "Apache-2.0"
+authors = [
+    {name = "Shamik Saha", email = "shamik.saha.rcciit@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Issues = "https://github.com/shamiksaharcciit-oss/onetrace-issues"
+
+[project.scripts]
+onetrace-explain = "onetrace_explain.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

onetrace_explain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

onetrace_explain-0.1.0/src/onetrace_explain/__init__.py

@@ -0,0 +1,9 @@
+"""onetrace-explain: a suggested explanation of a onetrace comparison, AI-generated and checked
+against the record. A separate package, installed on purpose: onetrace, onetrace-verify and the
+console neither depend on it nor import it."""
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("onetrace-explain")
+except importlib.metadata.PackageNotFoundError:          # run from its source tree
+    __version__ = "0.1.0"

onetrace_explain-0.1.0/src/onetrace_explain/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

onetrace_explain-0.1.0/src/onetrace_explain/cli.py

@@ -0,0 +1,167 @@
+"""`onetrace-explain REPORT_DIR [--model PROVIDER:NAME] [--dry-run] [--include-text] [--redact NAME]...
+[--yes] [--out DIR]`: a suggested explanation of a comparison, AI-generated and checked against the
+record. Never a verdict: onetrace's verdicts and exit codes are what they are without it.
+
+Exit codes are this command's own and say nothing about the runs: 0 an explanation or a dry run was
+written; 2 a usage error or the comparison can't be explained; 3 the model couldn't be reached or
+replied with no usable JSON. Never use it as a CI gate.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+from . import packet as pk
+from . import postcheck, providers
+from .record import record
+
+LABEL = "Suggested explanation — AI-generated, may be wrong"
+SENT = providers.CONFIG.parent / "explain-sent.json"
+WORDS = {"lead": "possible culprit", "ruled out": "ruled out", "note": "note"}
+
+
+def _sent() -> dict:
+    try:
+        return json.loads(SENT.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _remember(endpoint: str, kinds) -> None:
+    got = _sent()
+    got[endpoint] = sorted(set(got.get(endpoint, [])) | set(kinds))
+    SENT.parent.mkdir(parents=True, exist_ok=True)
+    SENT.write_text(json.dumps(got, indent=1, sort_keys=True), encoding="utf-8")
+
+
+def _command(check: dict, runs: dict) -> str:
+    a, b = runs["baseline"], runs["candidate"]
+    c = check["check"]
+    if c == "text":
+        return f"onetrace diff {a} {b} --text --stage {check['node']}"
+    if c == "for":
+        return f"onetrace localize {a} {b} --for {check['node']}"
+    if c == "mask":
+        return f"onetrace diff {a} {b} --mask <a mask naming {check['setting']}>"
+    if c == "reproduce":
+        return f"onetrace reproduce {runs[check['run']]} {check['node']} --runner <your runner>"
+    return f"onetrace match {runs[check['run']]}"
+
+
+def _fixes(claim: dict, items: dict) -> list:
+    """For a lead citing a recorded setting or version that changed, the one suggestion version 1
+    makes: set it back and run again. Built from the cited items, never from the model's words."""
+    out = []
+    for cid in claim["cites"]:
+        it = items[cid]
+        node = cid.split("/")[1] if cid.startswith("node/") else None
+        if it["kind"] == "constant" and not it.get("redacted"):
+            out.append(f"`{it['name']}` changed from `{it['baseline']}` to `{it['candidate']}` at `{node}`; "
+                       f"set it back and run again to check")
+        elif it["kind"] == "instrument":
+            va, vb = (it.get("baseline") or {}).get("version"), (it.get("candidate") or {}).get("version")
+            if va != vb:
+                out.append(f"`{(it.get('candidate') or {}).get('id')}` version changed from `{va}` to `{vb}` at "
+                           f"`{node}`; set it back and run again to check")
+    return out
+
+
+def text(model_label: str, checked: dict, packet: dict, runs: dict) -> str:
+    items = pk.by_id(packet)
+    L = [LABEL, f"model: {model_label}", ""]
+    if not checked["claims"]:
+        L.append("No suggestion could be tied to the record.")
+    for c in checked["claims"]:
+        L.append(f"- {WORDS[c['kind']]}: {c['text']}")
+        L.append(f"  shown by: {', '.join(c['cites'])}")
+        if c["kind"] == "lead":
+            for f in _fixes(c, items):
+                L.append(f"  to check: {f}")
+    if checked["dropped"]:
+        L.append("")
+        L.append("dropped: " + "; ".join(f"{n} {why}" for why, n in sorted(checked["dropped"].items())))
+    if checked["checks"]:
+        L.append("")
+        L.append("checks onetrace can run (a lead is confirmed or ruled out only by what these report):")
+        for k in checked["checks"]:
+            L.append(f"  {_command(k, runs)}")
+    if checked["checks_dropped"]:
+        L.append("checks dropped: " + "; ".join(f"{n} {why}" for why, n in sorted(checked["checks_dropped"].items())))
+    return "\n".join(L) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="onetrace-explain", description=__doc__.split("\n\n")[0])
+    ap.add_argument("report_dir")
+    ap.add_argument("--model")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.add_argument("--include-text", action="store_true")
+    ap.add_argument("--redact", action="append", default=[])
+    ap.add_argument("--yes", action="store_true")
+    ap.add_argument("--out")
+    try:
+        args = ap.parse_args(argv)
+    except SystemExit as e:
+        return 2 if e.code else 0
+    folder = Path(args.report_dir)
+    try:
+        packet = pk.build(folder, include_text=args.include_text, redact=args.redact)
+    except pk.PacketError as e:
+        print(f"onetrace-explain: {e}", file=sys.stderr)
+        return 2
+    raw = pk.dumps(packet)
+    if args.dry_run:
+        sys.stdout.buffer.write(raw + b"\n")
+        print(f"{len(raw)} bytes, sha256 {hashlib.sha256(raw).hexdigest()}; dry run: nothing sent")
+        return 0
+    try:
+        model = providers.load(args.model)
+    except providers.ModelUnavailable as e:
+        print(f"onetrace-explain: {e}", file=sys.stderr)
+        return 2
+    new = sorted(set(packet["kinds"]) - set(_sent().get(model.endpoint, [])))
+    if new and model.provider != "fake":
+        print(f"onetrace-explain: this sends to {model.endpoint} kinds of item it never sent there before: "
+              f"{', '.join(new)}")
+        if "constant" in new and any(i.get("kind") == "constant" and not i.get("redacted")
+                                     for i in packet.get("items") or []):
+            print("onetrace-explain: constants go with their values as the runs recorded them, whatever "
+                  "they hold; --redact NAME sends a constant's name and digests only")
+        if not args.yes:
+            if not sys.stdin.isatty():
+                print("onetrace-explain: not confirmed; run it in a terminal, or pass --yes", file=sys.stderr)
+                return 2
+            if input("Send? [y/N] ").strip().lower() not in ("y", "yes"):
+                print("onetrace-explain: nothing sent")
+                return 2
+    rep = json.loads((folder / packet["report"]["name"]).read_bytes())
+    runs = {s: rep["inputs"][s]["path"] for s in ("baseline", "candidate")}
+
+    def check(reply: bytes) -> dict:
+        return postcheck.check(packet, postcheck.parse(reply.decode("utf-8", "replace")))
+    out = Path(args.out) if args.out else folder
+    try:
+        run, checked = record(out, folder, packet, raw, model, model.ask, check)
+    except providers.ModelUnavailable as e:
+        print(f"onetrace-explain: the model couldn't be reached: {e}; no explanation written", file=sys.stderr)
+        return 3
+    except postcheck.ReplyError as e:
+        print(f"onetrace-explain: {e}; no explanation written", file=sys.stderr)
+        return 3
+    if model.provider != "fake":
+        _remember(model.endpoint, packet["kinds"])
+    shown = text(model.label, checked, packet, runs)
+    (run.parent / f"{run.name}.explanation.json").write_text(
+        json.dumps({"label": LABEL, "model": model.label, "record": run.name, **checked}, indent=1, sort_keys=True),
+        encoding="utf-8")
+    (run.parent / f"{run.name}.explanation.txt").write_text(shown, encoding="utf-8")
+    sys.stdout.write(shown)
+    print(f"recorded: {run}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

onetrace_explain-0.1.0/src/onetrace_explain/packet.py

@@ -0,0 +1,200 @@
+"""The evidence packet, `onetrace-explain-evidence/0.1`: what a model is shown, and all it is shown.
+
+Built deterministically from what a `diff` or `localize` run wrote in its report folder and the two
+runs that report names: the same report gives the same bytes. Every item carries an `id`, the
+place it came from, which is what a claim must cite. By default the packet holds the verdicts,
+stage names and edges, outcome classes, digests and byte counts, instrument names and versions,
+and the constants that differ with both values. A constant's value goes as the run recorded it,
+whatever it holds (a path, a token): `redact` sends that constant's name and digests only. The same
+holds for the report's annotations, which may name an input's folders. Nothing is read from this
+machine beyond the report and the two runs: no path of its own folders, no environment variable, no
+model key, no signing key, no anchor's proof. Kept text goes in only with `include_text=True`.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+FORMAT = "onetrace-explain-evidence/0.1"
+REPORTS = ("localize.json", "diff.json")
+TEXT_TYPES = ("text/", "application/json", "application/x-ndjson", "application/jsonl")
+TEXT_CAP = 8192            # bytes of kept text per output and run, when asked for
+
+
+class PacketError(ValueError):
+    """The report folder can't be explained: no report, a run that changed since it, or a report
+    whose verdict was not reached on checked records."""
+
+
+def dumps(obj) -> bytes:
+    """The packet's bytes: sorted keys, no spaces, UTF-8. Built twice from one report, the same."""
+    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+
+def _sha(raw: bytes) -> str:
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _report(folder: Path):
+    for name in REPORTS:
+        p = folder / name
+        if p.is_file():
+            raw = p.read_bytes()
+            return name, raw, json.loads(raw)
+    raise PacketError(f"{folder}: no localize.json or diff.json; run onetrace diff or localize with --out first")
+
+
+def _receipts(run: Path) -> tuple[dict, list]:
+    man_raw = (run / "MANIFEST.json").read_bytes()
+    man = json.loads(man_raw)
+    out = []
+    for e in man.get("chain") or []:
+        r = json.loads((run / e["file"]).read_bytes())
+        out.append((Path(e["file"]).stem, r))
+    return man, out
+
+
+def _node_id(r: dict) -> str:
+    st = r.get("stage") or {}
+    return st.get("name", "") + ("#" + st["instance"] if st.get("instance") else "")
+
+
+def _files(items) -> dict:
+    return {i.get("name"): i for i in items or [] if isinstance(i, dict) and isinstance(i.get("name"), str)}
+
+
+def _kept_text(run: Path, stem: str, item: dict):
+    p = run / "artifacts" / stem / str(item.get("name"))
+    if not p.is_file():
+        return None
+    raw = p.read_bytes()
+    if _sha(raw) != item.get("digest") or not str(item.get("media_type", "")).startswith(TEXT_TYPES):
+        return None
+    try:
+        text = raw[:TEXT_CAP].decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+    return text + ("" if len(raw) <= TEXT_CAP else f"\n[... {len(raw) - TEXT_CAP} more bytes not sent]")
+
+
+def build(report_dir, include_text: bool = False, redact=()) -> dict:
+    """The packet for the comparison in `report_dir`. Raises PacketError when it can't be built."""
+    folder = Path(report_dir)
+    rname, rraw, rep = _report(folder)
+    if rep.get("envelope") in ("refused", "could not check") or "ladder" not in rep:
+        raise PacketError(f"{folder}: the report's verdict is {rep.get('envelope')!r}: there is no checked "
+                          f"comparison to explain")
+    runs, receipts = {}, {}
+    for side in ("baseline", "candidate"):
+        inp = (rep.get("inputs") or {}).get(side) or {}
+        run = Path(inp.get("path", ""))
+        try:
+            man, recs = _receipts(run)
+        except (OSError, ValueError) as e:
+            raise PacketError(f"{side} run {run}: can't be read ({type(e).__name__})") from None
+        want = (inp.get("record_digests") or {}).get("chain_head")
+        if want is not None and man.get("chain_head") != want:
+            raise PacketError(f"{side} run {run}: its chain head is not the one the report checked; run the "
+                              f"comparison again")
+        runs[side] = {"run_id": inp.get("run_id"), "chain_head": man.get("chain_head"),
+                      "format": man.get("format"), "path": run}
+        receipts[side] = {_node_id(r): (stem, r) for stem, r in recs}
+    redact = set(redact or ())
+    items, kinds = [], set()
+
+    def add(kind, id_, **body):
+        kinds.add(kind)
+        items.append({"id": id_, "kind": kind, **body})
+
+    add("verdict", "comparison/verdict", verb=rep.get("verb"), envelope=rep.get("envelope"), exit=rep.get("exit"),
+        first_difference=list(rep.get("first_difference_frontier") or
+                               ([rep["first_difference"]["stage"]] if isinstance(rep.get("first_difference"), dict) else [])))
+    if isinstance(rep.get("for"), dict):
+        f = rep["for"]
+        add("for", "comparison/for", node=f.get("stage"), result=f.get("result"),
+            origins=list(f.get("origins") or []), not_reaching=list(f.get("not_reaching") or []),
+            path=[{"node": p.get("stage"), "verdict": p.get("verdict")}
+                  for p in f.get("path") or [] if isinstance(p, dict)])
+    if rep.get("end_outputs"):
+        add("end_outputs", "comparison/end_outputs", outputs=rep["end_outputs"])
+    if rep.get("inputs_differ"):
+        add("inputs_differ", "comparison/inputs_differ", inputs_differ=rep["inputs_differ"],
+            on_different_inputs=rep.get("on_different_inputs", "false"))
+    if isinstance(rep.get("mask"), dict):
+        add("mask", "comparison/mask", sha256=rep["mask"].get("sha256"),
+            settings_masked=len(rep.get("settings_masked") or []))
+    for row in rep.get("ladder") or []:
+        node = row.get("node") or row.get("stage")
+        if not isinstance(node, str):
+            continue
+        pre = f"node/{node}"
+        add("node", pre, node=node, verdict=row.get("verdict"), annotations=list(row.get("annotations") or []))
+        ra = (receipts["baseline"].get(node) or (None, None))
+        rb = (receipts["candidate"].get(node) or (None, None))
+        a, b = ra[1] or {}, rb[1] or {}
+        ia, ib = a.get("instrument") or {}, b.get("instrument") or {}
+        pick = lambda i: {k: i.get(k) for k in ("id", "kind", "version", "config_digest") if k in i}
+        add("instrument", f"{pre}/instrument", baseline=pick(ia), candidate=pick(ib))
+        add("outcome", f"{pre}/outcome", baseline=(a.get("outcome") or {}).get("class"),
+            candidate=(b.get("outcome") or {}).get("class"))
+        ups = sorted({i["name"][len("receipt:"):] for r in (a, b) for i in r.get("inputs") or []
+                      if isinstance(i, dict) and str(i.get("name", "")).startswith("receipt:")})
+        if ups:
+            add("upstream", f"{pre}/upstream", nodes=ups)
+        ca = ((a.get("assertions") or {}).get("constants") or {})
+        cb = ((b.get("assertions") or {}).get("constants") or {})
+        for k in sorted(set(ca) | set(cb)):
+            if ca.get(k) == cb.get(k):
+                continue
+            if k in redact:
+                add("constant", f"{pre}/constant/{k}", name=k, redacted=True,
+                    baseline=_sha(str(ca.get(k)).encode()) if k in ca else None,
+                    candidate=_sha(str(cb.get(k)).encode()) if k in cb else None)
+            else:
+                add("constant", f"{pre}/constant/{k}", name=k, baseline=ca.get(k), candidate=cb.get(k))
+        for which in ("inputs", "outputs"):
+            fa, fb = _files(a.get(which)), _files(b.get(which))
+            for n in sorted(set(fa) | set(fb)):
+                if n.startswith("receipt:"):
+                    continue                 # structure, given above as upstream
+                x, y = fa.get(n) or {}, fb.get(n) or {}
+                body = {"name": n, "baseline": {"digest": x.get("digest"), "bytes": x.get("bytes")} if x else None,
+                        "candidate": {"digest": y.get("digest"), "bytes": y.get("bytes")} if y else None,
+                        "differs": x.get("digest") != y.get("digest")}
+                add(which[:-1], f"{pre}/{which[:-1]}/{n}", **body)
+                if include_text and body["differs"] and which == "outputs" and x and y:
+                    ta = _kept_text(runs["baseline"]["path"], ra[0], x)
+                    tb = _kept_text(runs["candidate"]["path"], rb[0], y)
+                    if ta is not None and tb is not None:
+                        add("text", f"{pre}/output/{n}/text", name=n, baseline=ta, candidate=tb)
+    packet = {"format": FORMAT,
+              "report": {"name": rname, "sha256": _sha(rraw)},
+              "runs": {s: {k: v for k, v in r.items() if k != "path"} for s, r in runs.items()},
+              "items": items, "kinds": sorted(kinds)}
+    return packet
+
+
+def by_id(packet: dict) -> dict:
+    return {i["id"]: i for i in packet.get("items") or []}
+
+
+def values(item: dict) -> set:
+    """Every string an item holds, its own and inside its values: what a claim may quote from it."""
+    out = set()
+
+    def walk(v):
+        if isinstance(v, str):
+            out.add(v)
+        elif isinstance(v, (int, float)) and not isinstance(v, bool):
+            out.add(str(v))
+        elif isinstance(v, dict):
+            for x in v.values():
+                walk(x)
+        elif isinstance(v, list):
+            for x in v:
+                walk(x)
+    for k, v in item.items():
+        if k not in ("id", "kind"):
+            walk(v)
+    return out

onetrace_explain-0.1.0/src/onetrace_explain/postcheck.py

@@ -0,0 +1,168 @@
+"""The post-check: mechanical, no model. What a reply keeps, and what it loses and why.
+
+A reply is JSON: {"claims": [{"text", "kind", "cites": [item id, ...]}, ...], "checks": [{"check",
+...}, ...]}. A claim is kept only when its kind is one of `lead`, `ruled out` or `note`; it cites at
+least one item; every cite is an item of the packet; every value it quotes (in one of the quoting forms QUOTED lists; a form it doesn't list is read as unquoted text),
+and every unquoted token holding a digit or a slash, is a value or a name of an item it cites; and it says nothing is the cause of a difference
+("cause", "because", "due to", "led to", "resulted in", "the reason", "responsible for" and their
+like: a list of words, never a reading). A check is kept only when it is on the menu and every
+argument names something the packet holds. Nothing here reads the model's words for meaning.
+"""
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+
+from .packet import by_id, values
+
+KINDS = ("lead", "ruled out", "note")
+CAUSAL = re.compile(
+    r"\b(cause[sd]?|causing|causal(ly)?|because|due\s+to|owing\s+to|thanks\s+to"
+    r"|lead(s|ing)?\s+to|led\s+to|result(s|ed|ing)?\s+in|as\s+a\s+result|the\s+reasons?"
+    r"|reasons?\s+(for|why)|responsible\s+for|explains?\s+why|attributable|trigger(s|ed)?)\b",
+    re.IGNORECASE)
+# every quoting form a reply may use: backticks, straight and curly double and single quotes,
+# guillemets, low-high quotes; a straight single quote only between non-word characters, so an
+# apostrophe ("the run's") is not read as one
+QUOTED = re.compile("|".join([
+    r"`([^`]+)`", r"\"([^\"]+)\"", r"\u201c([^\u201d]+)\u201d", r"\u2018([^\u2019]+)\u2019",
+    r"\u00ab\s?([^\u00bb]+?)\s?\u00bb", r"\u00bb\s?([^\u00ab]+?)\s?\u00ab",
+    r"\u201e([^\u201c\u201d]+)[\u201c\u201d]", r"\u201d([^\u201d]+)\u201d", r"\u201f([^\u201d]+)\u201d",
+    r"\u2039\s?([^\u203a]+?)\s?\u203a", r"\u203a\s?([^\u2039]+?)\s?\u2039",
+    r"\u300c([^\u300d]+)\u300d", r"\u300e([^\u300f]+)\u300f", r"\uff02([^\uff02]+)\uff02",
+    r"\u2033([^\u2033]+)\u2033", r"\u301d([^\u301e\u301f]+)[\u301e\u301f]", r"\uff07([^\uff07]+)\uff07",
+    r"(?<!\w)'([^'\n]+?)'(?!\w)"]))
+# an unquoted token that names a value: one holding a digit or a slash (a number, a version, a
+# size, a path); it must be a value or a name of an item the claim cites
+VALUE_TOKEN = re.compile(r"[\w.:/+@#-]*[\d/][\w.:/+@#-]*")
+# letters that look like Latin ones, folded before the causal words are looked for
+CONFUSABLE = str.maketrans({
+    # Cyrillic
+    "\u0430": "a", "\u0435": "e", "\u043e": "o", "\u0440": "p", "\u0441": "c", "\u0443": "y",
+    "\u0445": "x", "\u0456": "i", "\u0455": "s", "\u0458": "j", "\u04bb": "h", "\u0501": "d",
+    "\u051b": "q", "\u051d": "w", "\u0491": "r", "\u0410": "A", "\u0415": "E", "\u041e": "O",
+    "\u0420": "P", "\u0421": "C", "\u0425": "X", "\u0405": "S", "\u0406": "I", "\u0408": "J",
+    # Greek
+    "\u03bf": "o", "\u03b1": "a", "\u03b5": "e", "\u03c1": "p", "\u03c5": "u", "\u03bd": "v",
+    "\u03ba": "k", "\u03b9": "i", "\u03c4": "t", "\u039f": "O", "\u0391": "A", "\u0395": "E",
+    # Armenian
+    "\u0585": "o", "\u057d": "u", "\u0570": "h", "\u0578": "n", "\u0581": "g", "\u0566": "q",
+    # Latin letters that read as others: alpha, script g, dotless i, small capitals
+    "\u0251": "a", "\u0261": "g", "\u0131": "i", "\u1d00": "a", "\u0299": "b", "\u1d04": "c",
+    "\u1d05": "d", "\u1d07": "e", "\ua730": "f", "\u0262": "g", "\u029c": "h", "\u026a": "i",
+    "\u1d0a": "j", "\u1d0b": "k", "\u029f": "l", "\u1d0d": "m", "\u0274": "n", "\u1d0f": "o",
+    "\u1d18": "p", "\u0280": "r", "\ua731": "s", "\u1d1b": "t", "\u1d1c": "u", "\u1d20": "v",
+    "\u1d21": "w", "\u028f": "y", "\u1d22": "z"})
+CHECKS = {
+    "text": ("node",),
+    "for": ("node",),
+    "mask": ("setting",),
+    "reproduce": ("run", "node"),
+    "match": ("run",),
+}
+REASONS = ("not JSON", "unknown kind", "cites nothing", "cites an item the packet doesn't hold",
+           "quotes a value its cites don't hold", "says what caused a difference")
+
+
+class ReplyError(ValueError):
+    """The reply has no JSON object with claims: nothing in it can be checked."""
+
+
+def parse(raw: str) -> dict:
+    """The reply's JSON object: the whole reply, or the first {...} block in it."""
+    try:
+        obj = json.loads(raw)
+    except ValueError:
+        m = re.search(r"\{.*\}", raw, re.DOTALL)
+        if not m:
+            raise ReplyError("the reply holds no JSON object") from None
+        try:
+            obj = json.loads(m.group(0))
+        except ValueError:
+            raise ReplyError("the reply's JSON doesn't parse") from None
+    if not isinstance(obj, dict) or not isinstance(obj.get("claims", []), list):
+        raise ReplyError("the reply's JSON has no list of claims")
+    return obj
+
+
+def _claim_problem(c, items) -> str | None:
+    if not isinstance(c, dict) or not isinstance(c.get("text"), str):
+        return "not JSON"
+    if c.get("kind") not in KINDS:
+        return "unknown kind"
+    cites = c.get("cites")
+    if not isinstance(cites, list) or not cites or not all(isinstance(x, str) for x in cites):
+        return "cites nothing"
+    if any(x not in items for x in cites):
+        return "cites an item the packet doesn't hold"
+    held = set().union(*(values(items[x]) for x in cites))
+    names = (held | set(cites) | {part for x in cites for part in x.split("/")}
+             | {part for v in held for part in re.split(r"[\s/]+", v) if part})
+    text = c["text"]
+    for m in QUOTED.finditer(text):
+        q = next(g for g in m.groups() if g is not None)
+        if q not in held and q not in cites:
+            return "quotes a value its cites don't hold"
+    for tok in VALUE_TOKEN.findall(QUOTED.sub(" ", text)):
+        tok = tok.strip(".:,;-")
+        if tok and tok not in names:
+            return "quotes a value its cites don't hold"
+    if CAUSAL.search(_folded(text)):
+        return "says what caused a difference"
+    return None
+
+
+def _folded(text: str) -> str:
+    """The text as the causal words are looked for in it: decomposed, with nonspacing combining marks
+    (Unicode category Mn) and format characters (Cf) (a soft hyphen, a zero-width space) removed, the
+    look-alike letters CONFUSABLE lists folded to Latin ones (the table above, which names the scripts
+    it covers), then NFKC."""
+    t = unicodedata.normalize("NFKD", text)
+    t = "".join(ch for ch in t if unicodedata.category(ch) not in ("Cf", "Mn"))
+    return unicodedata.normalize("NFKC", t.translate(CONFUSABLE))
+
+
+def _nodes(packet) -> set:
+    return {i["node"] for i in packet.get("items") or [] if i.get("kind") == "node"}
+
+
+def _settings(packet) -> set:
+    return {i["name"] for i in packet.get("items") or [] if i.get("kind") == "constant"}
+
+
+def _check_problem(k, packet) -> str | None:
+    if not isinstance(k, dict) or k.get("check") not in CHECKS:
+        return "not on the menu"
+    for arg in CHECKS[k["check"]]:
+        v = k.get(arg)
+        if arg == "node" and v not in _nodes(packet):
+            return "names a node the packet doesn't hold"
+        if arg == "setting" and v not in _settings(packet):
+            return "names a setting the packet doesn't hold"
+        if arg == "run" and v not in ("baseline", "candidate"):
+            return "names a run other than baseline or candidate"
+    return None
+
+
+def check(packet: dict, reply: dict) -> dict:
+    """{"claims": kept, "checks": kept, "dropped": {reason: count}, "checks_dropped": {reason: count}},
+    each count a decimal string."""
+    items = by_id(packet)
+    kept, dropped = [], {}
+    for c in reply.get("claims") or []:
+        why = _claim_problem(c, items)
+        if why is None:
+            kept.append({"text": c["text"], "kind": c["kind"], "cites": list(c["cites"])})
+        else:
+            dropped[why] = dropped.get(why, 0) + 1
+    checks, cdropped = [], {}
+    for k in reply.get("checks") or []:
+        why = _check_problem(k, packet)
+        if why is None:
+            checks.append({a: k[a] for a in ("check",) + CHECKS[k["check"]]})
+        else:
+            cdropped[why] = cdropped.get(why, 0) + 1
+    # counts as decimal strings: the record keeps no JSON numbers
+    return {"claims": kept, "checks": checks, "dropped": {k: str(v) for k, v in dropped.items()},
+            "checks_dropped": {k: str(v) for k, v in cdropped.items()}}

onetrace_explain-0.1.0/src/onetrace_explain/providers.py

@@ -0,0 +1,128 @@
+"""The model: an OpenAI-compatible chat endpoint (which covers local servers) or the Anthropic
+Messages API, named in ~/.config/onetrace/explain.toml or with --model. The key is read from the
+environment variable the config names; it is never written anywhere. `fake:PATH` replies with a
+file's bytes and makes no network call (tests, and seeing the flow without a model).
+
+The one network call this package makes is `Model.ask`, and only to the endpoint configured.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CONFIG = Path(os.environ.get("ONETRACE_EXPLAIN_CONFIG", Path.home() / ".config" / "onetrace" / "explain.toml"))
+TIMEOUT = 120
+
+SYSTEM = """You are shown an evidence packet from onetrace, a tool that records each stage of a pipeline
+and compares two runs. Suggest where a person should look. Reply with one JSON object only:
+{"claims": [{"text": "...", "kind": "lead" | "ruled out" | "note", "cites": ["<item id>", ...]}],
+ "checks": [{"check": "text" | "for" | "mask" | "reproduce" | "match", "node": "...", "setting": "...",
+ "run": "baseline" | "candidate"}]}
+Rules: every claim cites the ids of the packet items it rests on; quote values only as they appear
+in those items, in `backticks`; a lead is a possible culprit, never a certainty; never say that
+anything caused a difference. Claims that break a rule are dropped before anyone reads them."""
+
+
+class ModelUnavailable(RuntimeError):
+    """The model couldn't be reached, or replied with nothing to read."""
+
+
+@dataclass
+class Model:
+    provider: str                      # "openai", "anthropic" or "fake"
+    name: str                          # the model's own name, or the fake reply's path
+    base_url: str = ""
+    key_env: str = ""
+    params: dict = field(default_factory=lambda: {"temperature": "0", "max_tokens": "2000"})
+
+    @property
+    def label(self) -> str:
+        return f"{self.provider}:{self.name}"
+
+    @property
+    def endpoint(self) -> str:
+        """Where a packet goes, as the first-send confirmation names it: never the key."""
+        if self.provider == "fake":
+            return "fake (no network)"
+        if not self.base_url:
+            return "https://api.anthropic.com"
+        u = urllib.parse.urlsplit(self.base_url)
+        host = u.hostname or ""
+        if u.port:
+            host += f":{u.port}"
+        return urllib.parse.urlunsplit((u.scheme, host, u.path, "", ""))
+
+    def ask(self, packet_bytes: bytes) -> bytes:
+        """The model's raw reply text, as bytes, exactly as it came back."""
+        if self.provider == "fake":
+            try:
+                return Path(self.name).read_bytes()
+            except OSError as e:
+                raise ModelUnavailable(f"fake reply {self.name}: {type(e).__name__}") from None
+        key = os.environ.get(self.key_env, "") if self.key_env else ""
+        if self.key_env and not key:
+            raise ModelUnavailable(f"the environment variable {self.key_env} the config names is not set")
+        user = packet_bytes.decode("utf-8")
+        mt = int(self.params.get("max_tokens", "2000"))
+        temp = float(self.params.get("temperature", "0"))
+        if self.provider == "anthropic":
+            url = _join(self.base_url or "https://api.anthropic.com", "/v1/messages")
+            body = {"model": self.name, "max_tokens": mt, "temperature": temp, "system": SYSTEM,
+                    "messages": [{"role": "user", "content": user}]}
+            headers = {"content-type": "application/json", "anthropic-version": "2023-06-01", "x-api-key": key}
+        elif self.provider == "openai":
+            url = _join(self.base_url, "/chat/completions")
+            body = {"model": self.name, "max_tokens": mt, "temperature": temp,
+                    "messages": [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}]}
+            headers = {"content-type": "application/json"}
+            if key:
+                headers["authorization"] = f"Bearer {key}"
+        else:
+            raise ModelUnavailable(f"provider {self.provider!r} is not one of openai, anthropic, fake")
+        req = urllib.request.Request(url, data=json.dumps(body).encode(), headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
+                reply = json.loads(r.read())
+        except (urllib.error.URLError, OSError, ValueError) as e:
+            raise ModelUnavailable(f"{self.endpoint}: {type(e).__name__}: {getattr(e, 'reason', e)}") from None
+        try:
+            if self.provider == "anthropic":
+                text = "".join(b.get("text", "") for b in reply["content"] if b.get("type") == "text")
+            else:
+                text = reply["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError):
+            raise ModelUnavailable(f"{self.endpoint}: the reply has no message text") from None
+        return text.encode("utf-8")
+
+
+def _join(base: str, suffix: str) -> str:
+    """The endpoint's path with the suffix added, its query kept after it, never inside it."""
+    u = urllib.parse.urlsplit(base)
+    return urllib.parse.urlunsplit((u.scheme, u.netloc, u.path.rstrip("/") + suffix, u.query, ""))
+
+
+def load(spec: str | None) -> Model:
+    """The model: from `--model` (`fake:PATH`, `openai:NAME`, `anthropic:NAME`), else the config
+    file's [model] table (provider, name, base_url, key_env, and optional params)."""
+    cfg = {}
+    if CONFIG.is_file():
+        import tomllib
+        cfg = tomllib.loads(CONFIG.read_text(encoding="utf-8")).get("model", {})
+    if spec:
+        provider, _, name = spec.partition(":")
+        if not name:
+            raise ModelUnavailable(f"--model {spec!r}: give it as provider:name (fake:PATH, openai:NAME, "
+                                   f"anthropic:NAME)")
+        cfg = dict(cfg, provider=provider, name=name)
+    if not cfg.get("provider") or not cfg.get("name"):
+        raise ModelUnavailable(f"no model is configured: pass --model, or write [model] in {CONFIG}")
+    if cfg["provider"] == "openai" and not cfg.get("base_url"):
+        raise ModelUnavailable(f"an openai-compatible model needs base_url in {CONFIG}")
+    params = {k: str(v) for k, v in (cfg.get("params") or {}).items()}
+    return Model(cfg["provider"], cfg["name"], cfg.get("base_url", ""), cfg.get("key_env", ""),
+                 dict({"temperature": "0", "max_tokens": "2000"}, **params))

onetrace_explain-0.1.0/src/onetrace_explain/record.py

@@ -0,0 +1,70 @@
+"""Every explanation is itself a onetrace run (EX-6), written under OUT/explain/<run id>/, with
+three stages: `evidence` (the report and both runs' receipts, by digest, in; the packet out),
+`model` (the provider and model as its instrument, the request parameters as its settings; the raw
+reply out, `model-generated`) and `post_check` (what was kept and dropped). onetrace-verify reads it
+like any run.
+"""
+from __future__ import annotations
+
+import datetime
+import json
+from pathlib import Path
+
+from onetrace.emit import Instrument, Recorder
+
+from . import __version__
+
+STAGES = ["evidence", "model", "post_check"]
+OA = "operator-authored"
+
+
+def _run_id() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H-%M-%S.%fZ")
+
+
+def record(out: Path, report_dir: Path, packet: dict, packet_bytes: bytes, model, ask, check) -> tuple[Path, dict]:
+    """Run the three stages, recording each; returns (the run folder, the post-check's result).
+    `ask(packet_bytes) -> raw reply bytes` and `check(raw) -> result` are called inside their stages,
+    so a model that can't be reached leaves its stage's error receipt, and nothing that looks like
+    an explanation."""
+    run_id = _run_id()
+    folder = Path(out) / "explain" / run_id
+    rec = Recorder(folder, run_id=run_id, declared_stages=STAGES, manifest=Path(__file__),
+                   policy="fail-closed", anchor_reason="an explanation is a suggestion, kept for review",
+                   topology=True)
+    tool = lambda i, cfg=None: Instrument(i, "explain", __version__, dict(cfg or {}), "true")
+    result = {}
+
+    @rec.stage("evidence", tool("onetrace-explain-evidence"))
+    def evidence(ctx):
+        rep = report_dir / packet["report"]["name"]
+        ctx.reference(rep, "application/json", name=f"report/{rep.name}", trust_class=OA)
+        for side in ("baseline", "candidate"):
+            run = Path(json.loads(rep.read_bytes())["inputs"][side]["path"])
+            man = json.loads((run / "MANIFEST.json").read_bytes())
+            ctx.reference(run / "MANIFEST.json", "application/json", name=f"{side}/MANIFEST.json", trust_class=OA)
+            for e in man.get("chain") or []:
+                ctx.reference(run / e["file"], "application/json", name=f"{side}/{e['file']}", trust_class=OA)
+        ctx.write("packet.json", packet_bytes, "application/json", trust_class=OA)
+
+    @rec.stage("model", Instrument(model.provider, "model", model.name, dict(model.params), "false",
+                                   "a model's reply is not rederived"))
+    def ask_model(ctx):
+        ctx.read_receipt("evidence")
+        raw = ask(packet_bytes)
+        result["raw"] = raw
+        ctx.write("reply.txt", raw, "text/plain", trust_class="model-generated")
+
+    @rec.stage("post_check", tool("onetrace-explain-post-check"))
+    def post_check(ctx):
+        ctx.read_receipt("model")
+        result["checked"] = check(result["raw"])
+        ctx.write_json("checked.json", result["checked"], trust_class=OA)
+
+    try:
+        evidence()
+        ask_model()
+        post_check()
+    finally:
+        rec.close()
+    return folder, result.get("checked")

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: onetrace-explain
+Version: 0.1.0
+Summary: A suggested explanation of a onetrace comparison: AI-generated, checked against the record, never a verdict
+Author-email: Shamik Saha <shamik.saha.rcciit@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Issues, https://github.com/shamiksaharcciit-oss/onetrace-issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: onetrace<0.5,>=0.4
+
+# onetrace-explain
+
+A suggested explanation of a onetrace comparison: **AI-generated, may be wrong**, and checked
+against the record before anyone reads it. Never a verdict: onetrace's verdicts and exit codes are
+what they are without it, and its exit codes say nothing about the runs. Don't use it as a CI gate.
+
+```
+onetrace localize runs/a runs/b --for answer --out report
+onetrace-explain report --dry-run          # the packet exactly as it would be sent; nothing sent
+onetrace-explain report --model anthropic:<model name>
+```
+
+- **What is sent:** a packet built from the report and the two runs' receipts: verdicts, stage
+  names and edges, outcome classes, digests and sizes, instrument names and versions, and the
+  constants that differ with both values (`--redact NAME` sends a name and digest only). Kept text
+  only with `--include-text`. A constant's value goes as the run recorded it, a path or a token
+  included; `--redact NAME` keeps it out. Never this machine's own paths, an environment variable,
+  the model key, a signing key or an anchor's proof. The first send of a kind of item to an endpoint asks first (`--yes` for scripts).
+- **The model:** yours, named in `~/.config/onetrace/explain.toml`:
+
+  ```toml
+  [model]
+  provider = "anthropic"          # or "openai" (any OpenAI-compatible endpoint, local ones too)
+  name = "<model name>"
+  key_env = "ANTHROPIC_API_KEY"   # the variable holding the key; the key is never written anywhere
+  # base_url = "http://localhost:8000/v1"   # for an openai-compatible server
+  ```
+- **The post-check,** with no model: a claim is dropped when it cites nothing, cites what the packet
+  doesn't hold, quotes a value its cites don't hold, or says what caused a difference. What's shown
+  says how many were dropped, and why.
+- **Checks, not conclusions:** each suggestion comes with onetrace commands to run. A lead is
+  confirmed or ruled out only by what those report.
+- **Recorded:** every explanation is a onetrace run of its own, under `<out>/explain/<run id>/`,
+  which `onetrace-verify` checks like any run.

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+MANIFEST.in
+README.md
+_reproducible_sdist.py
+pyproject.toml
+src/onetrace_explain/__init__.py
+src/onetrace_explain/__main__.py
+src/onetrace_explain/cli.py
+src/onetrace_explain/packet.py
+src/onetrace_explain/postcheck.py
+src/onetrace_explain/providers.py
+src/onetrace_explain/record.py
+src/onetrace_explain.egg-info/PKG-INFO
+src/onetrace_explain.egg-info/SOURCES.txt
+src/onetrace_explain.egg-info/dependency_links.txt
+src/onetrace_explain.egg-info/entry_points.txt
+src/onetrace_explain.egg-info/requires.txt
+src/onetrace_explain.egg-info/top_level.txt

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+onetrace-explain = onetrace_explain.cli:main

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/requires.txt

@@ -0,0 +1 @@
+onetrace<0.5,>=0.4

onetrace_explain-0.1.0/src/onetrace_explain.egg-info/top_level.txt

@@ -0,0 +1 @@
+onetrace_explain