Source code for dendritic_modeling.utils.project_evidence

"""Verify declared current-paper evidence without importing scientific code.

An integrity pass proves preservation of declared bytes only. It does not prove
that a figure's scientific workflow, source identity or numerical result is valid.
"""

from __future__ import annotations

import sys

if __name__ == "__main__" and not __package__:
    sys.path.pop(0)

import argparse
import hashlib
import json
import re
from pathlib import Path


[docs] class EvidenceError(ValueError): """An evidence manifest is invalid or does not identify preserved files."""
[docs] def sha256_file(path: Path) -> str: digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest()
[docs] def check_evidence(manifest: Path, roots: dict[str, Path]) -> dict: """Check explicit files and result mappings; never regenerate a baseline.""" data = json.loads(manifest.read_text()) if data.get("schema_version") != 1 or not data.get("project"): raise EvidenceError("Expected schema_version=1 and a project name") if not re.fullmatch(r"[0-9a-f]{40}", data.get("baseline_paper_commit", "")): raise EvidenceError("Record the original paper's full commit identity") files = data.get("files") results = data.get("results") if ( not isinstance(files, list) or not files or not isinstance(results, list) or not results ): raise EvidenceError("Declare nonempty files and results") indexed = {} checks = [] for row in files: name = row.get("id") if not isinstance(name, str) or not name or name in indexed: raise EvidenceError("File identifiers must be nonempty and unique") indexed[name] = row root_name = row.get("root") if root_name not in roots: raise EvidenceError(f"Missing explicit root: {root_name}") root = Path(roots[root_name]).resolve() relative = Path(row.get("path", "")) if not row.get("path") or relative.is_absolute() or ".." in relative.parts: raise EvidenceError(f"Expected contained relative file path: {relative}") path = (root / relative).resolve() if not path.is_relative_to(root): raise EvidenceError(f"Evidence path escapes its root: {relative}") expected = row.get("sha256", "") if not re.fullmatch(r"[0-9a-f]{64}", expected): raise EvidenceError(f"Invalid SHA-256 for {name}") actual = sha256_file(path) if path.is_file() else None checks.append( { "id": name, "path": str(path), "expected": expected, "actual": actual, "status": ( "match" if actual == expected else "missing" if actual is None else "changed" ), } ) identifiers = set() incomplete = [] for result in results: name = result.get("id") if not isinstance(name, str) or not name or name in identifiers: raise EvidenceError("Result identifiers must be nonempty and unique") identifiers.add(name) refs = [result.get("artifact"), *result.get("evidence", [])] if any(ref not in indexed for ref in refs): raise EvidenceError(f"Unbound file reference in result {name}") if not result.get("workflow_kind"): raise EvidenceError(f"Classify the computation for {name}") # Qualification is a recorded review decision with linked evidence. # This checker does not evaluate that evidence's scientific validity. if result.get("qualification") != "numerically_validated" or not result.get( "validation_evidence" ): incomplete.append(name) else: if any(ref not in indexed for ref in result["validation_evidence"]): raise EvidenceError(f"Unbound validation evidence for {name}") failures = [row for row in checks if row["status"] != "match"] return { "schema_version": 1, "project": data["project"], "manifest_sha256": sha256_file(manifest), "baseline_paper_commit": data["baseline_paper_commit"], "integrity": "failed" if failures else "passed", "checked_files": len(checks), "declared_results": len(results), "unqualified_results": incomplete, "unresolved_dependencies": data.get("missing_evidence", []), "checks": checks, "scientific_equivalence": "not assessed by file integrity verification", "coverage": "declared files/results only; not inferred dependency closure", }
def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--manifest", required=True, type=Path) parser.add_argument("--root", action="append", required=True, metavar="NAME=PATH") parser.add_argument("--report", type=Path, required=True) parser.add_argument("--require-qualified", action="store_true") args = parser.parse_args(argv) roots = {} for value in args.root: name, separator, path = value.partition("=") if not separator or not name or not path or name in roots: parser.error("Use unique --root NAME=PATH arguments") roots[name] = Path(path).resolve() report = args.report.resolve() if any(report.is_relative_to(root) for root in roots.values()): parser.error("Write the report outside all evidence roots") if report.exists(): parser.error("Refusing to overwrite an existing report") receipt = check_evidence(args.manifest, roots) report.parent.mkdir(parents=True, exist_ok=True) with report.open("x") as handle: json.dump(receipt, handle, indent=2) handle.write("\n") print(json.dumps({k: v for k, v in receipt.items() if k != "checks"}, indent=2)) return int( receipt["integrity"] != "passed" or ( args.require_qualified and bool( receipt["unqualified_results"] or receipt["unresolved_dependencies"] ) ) ) if __name__ == "__main__": raise SystemExit(main())