@heretek-ai/epistemic-swarm 0.2.2 → 0.3.0

package/runner/pcrb.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Proof-Carrying Research Brief (PCRB) — export side (Stream D).
+
+A PCRB is a self-contained signed bundle: the synthesis, every claim with its
+quote witness, the full text of every cited source, an integrity manifest, and
+an optional HMAC signature. A third party can re-verify everything WITHOUT
+trusting the LLM that produced it and WITHOUT access to the original
+.research/ workspace — verification runs against the bundled sources.
+
+Bundle shape (brief.pcrb.json):
+{
+  "pcrb_version": "1.0",
+  "objective": ..., "exported_at": ...,
+  "synthesis_markdown": ...,
+  "claims": [ {claim fields..., "witness": {quote, source_hash, confidence, verified_at}} ],
+  "sources": { "<hash>": {"url","title","tier","content"} },
+  "manifest": { "synthesis_markdown": sha, "claims": {id: sha}, "sources": {hash: sha} },
+  "signature": {"alg": "hmac-sha256" | "none", "key_id": ..., "sig": ...}
+}
+
+Member hashes use SourceHasher.compute_sha256 semantics so a bundled source's
+member hash equals its cache hash.
+
+Signing: stdlib hmac when a key is provided (env IUMBTEMS_PCRB_KEY or key
+file). alg="none" provides integrity (member-vs-manifest) but NOT authenticity
+— a coordinated rewrite of content + manifest is undetectable without a key.
+Real PKI (ed25519) is a gated follow-on; HMAC is sufficient for the tamper
+probe, not for the regulatory story.
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from runner.claim_witness import claims_from_dossier, load_dossier  # noqa: E402
+
+PCRB_VERSION = "1.0"
+ENV_KEY = "IUMBTEMS_PCRB_KEY"
+
+
+def canonical_json(obj: Any) -> str:
+    """Deterministic serialization for hashing/signing."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def sha256_text(text: str) -> str:
+    """SourceHasher.compute_sha256 semantics (strip + utf-8)."""
+    return hashlib.sha256(text.strip().encode("utf-8")).hexdigest()
+
+
+def member_hash(obj: Any) -> str:
+    """Hash a structured member via canonical JSON."""
+    return sha256_text(canonical_json(obj))
+
+
+def _resolve_key(key: Optional[str], key_path: Optional[Path]) -> Optional[bytes]:
+    if key:
+        return key.encode("utf-8")
+    env = os.environ.get(ENV_KEY)
+    if env:
+        return env.encode("utf-8")
+    if key_path and Path(key_path).exists():
+        return Path(key_path).read_bytes().strip()
+    return None
+
+
+def sign_manifest(manifest: Dict[str, Any], key: Optional[bytes], key_id: str = "local") -> Dict[str, Any]:
+    if not key:
+        return {"alg": "none", "key_id": None, "sig": None}
+    sig = hmac.new(key, canonical_json(manifest).encode("utf-8"), hashlib.sha256).hexdigest()
+    return {"alg": "hmac-sha256", "key_id": key_id, "sig": sig}
+
+
+def export_brief(
+    base_dir: Path,
+    out_path: Optional[Path] = None,
+    scope_ids: Optional[List[str]] = None,
+    objective: Optional[str] = None,
+    key: Optional[str] = None,
+    key_path: Optional[Path] = None,
+    key_id: str = "local",
+) -> Path:
+    """Assemble a PCRB from a .research workspace. Returns the bundle path."""
+    from skills.research_cache.hasher import SourceHasher
+
+    base_dir = Path(base_dir)
+    hasher = SourceHasher(base_dir)
+
+    # --- synthesis ---
+    synthesis = ""
+    final_md = base_dir / "final_synthesis.md"
+    if final_md.exists():
+        synthesis = final_md.read_text(encoding="utf-8")
+    else:
+        parts = sorted((base_dir / "scratchpads").glob("*/scope_synthesis.md"))
+        synthesis = "\n\n---\n\n".join(p.read_text(encoding="utf-8") for p in parts)
+
+    # --- claims + witnesses ---
+    scratch = base_dir / "scratchpads"
+    scope_dirs = (
+        [scratch / s for s in scope_ids]
+        if scope_ids
+        else (sorted(p for p in scratch.iterdir() if p.is_dir()) if scratch.exists() else [])
+    )
+    claim_records: List[Dict[str, Any]] = []
+    needed_hashes = set()
+
+    for scope_dir in scope_dirs:
+        for dossier_name in ("alpha_dossier.json", "beta_dossier.json"):
+            dpath = scope_dir / dossier_name
+            if not dpath.exists():
+                continue
+            dossier = load_dossier(dpath)
+            for c in claims_from_dossier(dossier):
+                rec = c.to_dict()
+                witness: Dict[str, Any] = {
+                    "quote": c.verbatim_quote,
+                    "source_hash": c.source_hash,
+                    "confidence": None,
+                    "verified_at": None,
+                }
+                if c.source_hash and c.verbatim_quote:
+                    passed, conf, _msg = hasher.verify_quote(c.source_hash, c.verbatim_quote)
+                    witness["confidence"] = float(conf)
+                    witness["verified_at"] = datetime.now(timezone.utc).isoformat()
+                    if passed and c.source_hash:
+                        needed_hashes.add(c.source_hash)
+                elif c.source_hash:
+                    needed_hashes.add(c.source_hash)
+                rec["witness"] = witness
+                claim_records.append(rec)
+
+    # --- bundled sources (self-contained: full text in the bundle) ---
+    sources: Dict[str, Dict[str, Any]] = {}
+    for src_hash in sorted(needed_hashes):
+        content = hasher.get_source_content(src_hash)
+        meta = hasher.get_source_metadata(src_hash) or {}
+        if content is None:
+            continue
+        sources[src_hash] = {
+            "url": meta.get("url"),
+            "title": meta.get("title"),
+            "tier": meta.get("tier"),
+            "content": content,
+        }
+
+    # --- manifest (integrity) ---
+    manifest: Dict[str, Any] = {
+        "synthesis_markdown": sha256_text(synthesis),
+        "claims": {rec["claim_id"]: member_hash(rec) for rec in claim_records},
+        "sources": {h: sha256_text(s["content"]) for h, s in sources.items()},
+    }
+
+    signature = sign_manifest(manifest, _resolve_key(key, key_path), key_id=key_id)
+
+    bundle = {
+        "pcrb_version": PCRB_VERSION,
+        "objective": objective
+        or (json.loads((base_dir / "manifest.json").read_text()).get("objective")
+            if (base_dir / "manifest.json").exists() else None),
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "synthesis_markdown": synthesis,
+        "claims": claim_records,
+        "sources": sources,
+        "manifest": manifest,
+        "signature": signature,
+    }
+
+    out = Path(out_path) if out_path else (base_dir / "brief.pcrb.json")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with open(out, "w", encoding="utf-8") as f:
+        json.dump(bundle, f, indent=2)
+    return out
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Export a proof-carrying research brief")
+    parser.add_argument("--dir", default=".research")
+    parser.add_argument("--out", default=None)
+    parser.add_argument("--scope", action="append", dest="scope_ids")
+    parser.add_argument("--objective", default=None)
+    parser.add_argument("--key-file", default=None)
+    parser.add_argument("--key-id", default="local")
+    args = parser.parse_args(argv)
+
+    path = export_brief(
+        Path(args.dir),
+        out_path=Path(args.out) if args.out else None,
+        scope_ids=args.scope_ids,
+        objective=args.objective,
+        key_path=Path(args.key_file) if args.key_file else None,
+        key_id=args.key_id,
+    )
+    print(json.dumps({"status": "exported", "path": str(path)}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runner/pcrb_verify.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+Proof-Carrying Research Brief (PCRB) — standalone verifier (Stream D).
+
+Verifies a brief.pcrb.json WITHOUT trusting the LLM that produced it and
+WITHOUT the original .research/ workspace: every quote is re-checked against
+the sources BUNDLED INSIDE the brief.
+
+Checks (all must pass for exit 0):
+  1. source identity  — sha256(source content) == its hash key in the bundle
+  2. manifest integrity — every member hash recomputes to the manifest value
+  3. signature — HMAC over the manifest (when alg != "none")
+  4. quotes — every claim's verbatim_quote re-verified against the bundled
+     source text, using the SAME verification stack as the auditor
+     (SourceHasher.verify_quote via a throwaway cache directory)
+
+Usage:
+  python3 runner/pcrb_verify.py brief.pcrb.json [--json] [--key-file ...]
+
+Exit codes: 0 = all checks passed, 1 = tampering/failure detected,
+2 = unreadable bundle.
+"""
+
+import argparse
+import hashlib
+import hmac
+import json
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+# Reuse the export-side canonicalization so hashes always agree.
+from runner.pcrb import (  # noqa: E402
+    ENV_KEY,
+    canonical_json,
+    member_hash,
+    sha256_text,
+)
+
+
+def verify_brief(
+    bundle: Dict[str, Any],
+    key: Optional[bytes] = None,
+) -> Dict[str, Any]:
+    """Run all checks. Returns a structured report dict."""
+    import os
+    started = time.perf_counter()
+    failures: List[Dict[str, str]] = []
+
+    manifest = bundle.get("manifest") or {}
+    signature = bundle.get("signature") or {}
+    claims = bundle.get("claims") or []
+    sources = bundle.get("sources") or {}
+
+    # --- 1. source identity ---
+    for src_hash, meta in sources.items():
+        content = meta.get("content") or ""
+        actual = sha256_text(content)
+        if actual != src_hash:
+            failures.append({
+                "check": "source_identity",
+                "member": src_hash,
+                "message": f"bundled source content hashes to {actual}, not its key {src_hash}",
+            })
+
+    # --- 2. manifest integrity ---
+    synth_hash = sha256_text(bundle.get("synthesis_markdown") or "")
+    if manifest.get("synthesis_markdown") != synth_hash:
+        failures.append({
+            "check": "manifest_integrity",
+            "member": "synthesis_markdown",
+            "message": "synthesis_markdown does not match its manifest hash",
+        })
+
+    for rec in claims:
+        cid = rec.get("claim_id", "UNKNOWN")
+        expected = (manifest.get("claims") or {}).get(cid)
+        actual = member_hash(rec)
+        if expected is None:
+            failures.append({"check": "manifest_integrity", "member": cid, "message": "claim missing from manifest"})
+        elif expected != actual:
+            failures.append({
+                "check": "manifest_integrity",
+                "member": cid,
+                "message": f"claim hash mismatch (manifest {expected[:16]}… vs actual {actual[:16]}…)",
+            })
+
+    for src_hash, meta in sources.items():
+        expected = (manifest.get("sources") or {}).get(src_hash)
+        actual = sha256_text(meta.get("content") or "")
+        if expected is None:
+            failures.append({"check": "manifest_integrity", "member": src_hash, "message": "source missing from manifest"})
+        elif expected != actual:
+            failures.append({
+                "check": "manifest_integrity",
+                "member": src_hash,
+                "message": "source content does not match its manifest hash",
+            })
+
+    # --- 3. signature ---
+    alg = signature.get("alg") or "none"
+    sig_status = "unsigned"
+    if alg == "hmac-sha256":
+        if not key:
+            sig_status = "unverifiable"
+            failures.append({
+                "check": "signature",
+                "member": "manifest",
+                "message": "brief is HMAC-signed but no key was provided (env IUMBTEMS_PCRB_KEY or --key-file)",
+            })
+        else:
+            expected_sig = hmac.new(key, canonical_json(manifest).encode("utf-8"), hashlib.sha256).hexdigest()
+            provided = signature.get("sig") or ""
+            if not hmac.compare_digest(expected_sig, provided):
+                sig_status = "invalid"
+                failures.append({
+                    "check": "signature",
+                    "member": "manifest",
+                    "message": "HMAC signature does not match manifest (manifest was rewritten or key differs)",
+                })
+            else:
+                sig_status = "valid"
+    # alg == "none": integrity-only mode — coordinated rewrites are NOT
+    # detectable without a key. Reported, not failed.
+
+    # --- 4. quotes against BUNDLED sources (single verification stack) ---
+    quotes_verified = 0
+    quotes_failed = 0
+    with tempfile.TemporaryDirectory(prefix="pcrb_verify_") as tmp:
+        from skills.research_cache.hasher import SourceHasher
+
+        hasher = SourceHasher(Path(tmp))
+        # Materialize bundled sources into the throwaway cache under their
+        # claimed hashes so verify_quote runs its exact/normalized/fuzzy ladder.
+        for src_hash, meta in sources.items():
+            content = meta.get("content") or ""
+            md_path = Path(tmp) / "sources" / f"{src_hash}.md"
+            md_path.parent.mkdir(parents=True, exist_ok=True)
+            md_path.write_text(content, encoding="utf-8")
+
+        for rec in claims:
+            cid = rec.get("claim_id", "UNKNOWN")
+            witness = rec.get("witness") or {}
+            src_hash = witness.get("source_hash") or rec.get("source_hash")
+            quote = witness.get("quote") or rec.get("verbatim_quote")
+            if not src_hash or not quote:
+                continue  # structural rules live in refinement.check_invariants
+            if src_hash not in sources:
+                quotes_failed += 1
+                failures.append({
+                    "check": "quote",
+                    "member": cid,
+                    "message": f"claim cites source {src_hash} which is not bundled",
+                })
+                continue
+            passed, conf, msg = hasher.verify_quote(src_hash, quote)
+            if passed:
+                quotes_verified += 1
+            else:
+                quotes_failed += 1
+                failures.append({
+                    "check": "quote",
+                    "member": cid,
+                    "message": f"quote not found in bundled source (conf={conf}): {msg}",
+                })
+
+    elapsed = time.perf_counter() - started
+    return {
+        "ok": not failures,
+        "failures": failures,
+        "checks": {
+            "source_identity": "pass" if not any(f["check"] == "source_identity" for f in failures) else "fail",
+            "manifest_integrity": "pass" if not any(f["check"] == "manifest_integrity" for f in failures) else "fail",
+            "signature": sig_status,
+            "quotes": "pass" if quotes_failed == 0 else "fail",
+        },
+        "stats": {
+            "claims": len(claims),
+            "sources": len(sources),
+            "quotes_verified": quotes_verified,
+            "quotes_failed": quotes_failed,
+            "elapsed_s": round(elapsed, 4),
+        },
+    }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Verify a proof-carrying research brief")
+    parser.add_argument("brief", help="Path to brief.pcrb.json")
+    parser.add_argument("--json", action="store_true", help="Print JSON report")
+    parser.add_argument("--key-file", default=None)
+    args = parser.parse_args(argv)
+
+    path = Path(args.brief)
+    if not path.exists():
+        print(f"error: no such brief: {path}", file=sys.stderr)
+        return 2
+    try:
+        bundle = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: unreadable brief: {exc}", file=sys.stderr)
+        return 2
+
+    import os
+
+    key = None
+    if args.key_file and Path(args.key_file).exists():
+        key = Path(args.key_file).read_bytes().strip()
+    elif os.environ.get(ENV_KEY):
+        key = os.environ[ENV_KEY].encode("utf-8")
+
+    report = verify_brief(bundle, key=key)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        status = "PASS" if report["ok"] else "FAIL"
+        print(f"[{status}] {path}")
+        for name, st in report["checks"].items():
+            print(f"  {name}: {st}")
+        for f in report["failures"]:
+            print(f"  ✗ [{f['check']}] {f['member']}: {f['message']}")
+        s = report["stats"]
+        print(f"  quotes verified: {s['quotes_verified']}/{s['claims']} in {s['elapsed_s']}s")
+
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())