recusal 0.1.0__py3-none-any.whl

recusal/__init__.py

@@ -0,0 +1,69 @@
+"""
+Recusal, separation-of-powers governance for Claude agents.
+
+A judge recuses themselves from a case they can't impartially decide. The same
+principle governs autonomous agents: the thing that *generates* the work must
+never be the thing that *certifies* it. Recusal is that independent authority -
+you collect evidence, it adjudicates deterministically into PASS / RETRY / FAIL,
+and it can **refuse to certify**. No model call in the decision path. Zero
+dependencies. Same evidence, same verdict, every time.
+
+The spine is the evidence contract (see ``evidence`` and docs/EVIDENCE.md):
+
+    Finding   one observation about the work.
+    Verdict   the decision those findings add up to.
+
+Everything hangs off it:
+
+- ``evidence``, ``Finding`` / ``Verdict`` / ``Severity`` / ``Decision`` and
+                 ``compute_verdict(findings)`` (the typed core).
+- ``checks``  , built-in deterministic checks that turn raw data into Findings.
+- ``claude``  , drop the gate in front of a Claude agent's tool calls so it can
+                 refuse *before* a tool runs.
+- ``gates``   , staged release checkpoints (G0-G8) rolled into release evidence.
+
+The constitution it encodes: **builders cannot grade their own work** ·
+deterministic before AI · the judge owns evidence, not progression · no shadow
+authority. (See CONSTITUTION.md.)
+
+Zero runtime dependencies, standard library only.
+"""
+
+from .audit import AuditLog, verify
+from .classify import (
+    DEFAULT_TAXONOMY,
+    Classification,
+    FailureClass,
+    classify_failure,
+    classify_verdict,
+)
+from .evidence import (
+    Decision,
+    Finding,
+    RuleSeverity,
+    Severity,
+    Verdict,
+    compute_verdict,
+)
+from .gates import GateAdjudicator, GateResult, ReleaseEvidence
+
+__all__ = [
+    "Severity",
+    "RuleSeverity",
+    "Finding",
+    "Verdict",
+    "Decision",
+    "compute_verdict",
+    "GateAdjudicator",
+    "GateResult",
+    "ReleaseEvidence",
+    "AuditLog",
+    "verify",
+    "classify_failure",
+    "classify_verdict",
+    "FailureClass",
+    "Classification",
+    "DEFAULT_TAXONOMY",
+]
+
+__version__ = "0.1.0"

recusal/audit.py

@@ -0,0 +1,177 @@
+"""
+Hash-chained audit log, a linked record of every verdict.
+
+A gate that can refuse is only half of an auditable control; the other half is a
+record you can replay and an auditor can read. ``recusal.audit`` appends each verdict to an
+append-only, hash-chained log: every entry carries the SHA-256 hash of the entry
+before it, so an **in-place edit or a reordering** of existing entries breaks the
+chain and ``verify`` catches it, naming the entry and the reason.
+
+What this does and does not guarantee (read before relying on it):
+
+- It detects in-place edits and reordering. It is tamper-**evident**, not tamper-proof.
+- The digest is **unkeyed** and the head is **unanchored**, so an attacker with write
+  access to the file can truncate the tail, or rewrite the whole chain and recompute every
+  hash, and still pass ``verify``. To catch those, commit the head ``(count, last_hash)``
+  somewhere the attacker cannot also rewrite (a witness, a WORM store, a signature) and
+  pass it as ``verify(..., expected_head=...)``.
+- It is **single-writer**: two processes appending to the same file will fork the chain.
+
+Deterministic and dependency-free: SHA-256 over canonical JSON, standard library only.
+The record shape maps cleanly onto OWASP Agentic logging and EU AI Act Article 12
+(record-keeping).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .evidence import Verdict
+
+GENESIS = "0" * 64  # the prev_hash of the first entry
+
+
+def _canonical(entry: Dict[str, Any]) -> str:
+    """Stable serialization of an entry for hashing, everything but the hash field."""
+    payload = {k: v for k, v in entry.items() if k != "hash"}
+    return json.dumps(
+        payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True, default=str
+    )
+
+
+def _digest(entry: Dict[str, Any]) -> str:
+    return hashlib.sha256(_canonical(entry).encode("utf-8")).hexdigest()
+
+
+def _summarize(verdict: Verdict) -> Dict[str, Any]:
+    return {
+        "decision": verdict.decision.value,
+        "highest_severity": verdict.highest_severity.value,
+        "reasons": verdict.reasons(),
+        "failures": [
+            {"check": f.check, "severity": f.severity.value, "message": f.message}
+            for f in verdict.failures
+        ],
+    }
+
+
+class AuditLog:
+    """Append-only, hash-chained log of verdicts.
+
+    Pass ``path`` to persist as JSONL (one entry per line); otherwise it lives in
+    memory on ``self.entries``. An existing file is resumed, the chain continues
+    from its last entry.
+    """
+
+    def __init__(
+        self,
+        path: Optional[str] = None,
+        *,
+        clock: Optional[Callable[[], datetime]] = None,
+    ) -> None:
+        self.path = path
+        self._clock = clock or (lambda: datetime.now(timezone.utc))
+        self.entries: List[Dict[str, Any]] = []
+        self.last_hash = GENESIS
+        if path:
+            for entry in load(path):
+                self.entries.append(entry)
+                head = entry.get("hash")
+                if head is not None:
+                    self.last_hash = head
+
+    def append(
+        self,
+        verdict: Verdict,
+        *,
+        action: Any = None,
+        actor: Optional[str] = None,
+        timestamp: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Record one verdict. ``action`` is any JSON-serializable description of what
+        was adjudicated (e.g. ``{"tool": "Bash", "command": "..."}``); ``actor`` is an
+        optional agent/session id. Returns the written entry (including its hash)."""
+        entry: Dict[str, Any] = {
+            "seq": len(self.entries),
+            "timestamp": timestamp or self._clock().isoformat(),
+            "actor": actor,
+            "action": action,
+            **_summarize(verdict),
+            "prev_hash": self.last_hash,
+        }
+        entry["hash"] = _digest(entry)
+
+        self.entries.append(entry)
+        self.last_hash = entry["hash"]
+        if self.path:
+            with open(self.path, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(entry, ensure_ascii=True, default=str) + "\n")
+        return entry
+
+
+def load(path: str) -> List[Dict[str, Any]]:
+    """Read a JSONL audit file into a list of entries (empty if the file is absent).
+
+    A line that is not valid JSON (e.g. a partial final line left by a process killed
+    mid-append) is skipped rather than crashing the read, so a half-written tail can never
+    brick the log. ``verify`` still surfaces any resulting chain break.
+    """
+    entries: List[Dict[str, Any]] = []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue  # skip a corrupt/partial line instead of bricking the log
+    except FileNotFoundError:
+        return []
+    return entries
+
+
+def verify(
+    entries: List[Dict[str, Any]],
+    *,
+    expected_head: Optional[Tuple[int, str]] = None,
+) -> Tuple[bool, List[str]]:
+    """Check the hash chain. Returns ``(intact, problems)``, ``problems`` is empty when the
+    log is intact, otherwise it names each broken entry and why.
+
+    This detects in-place edits and reordering of existing entries. It does **not**, on its
+    own, detect truncation of the tail or a full re-hash by an attacker with write access
+    (the digest is unkeyed and the head is unanchored). Pass ``expected_head=(count,
+    last_hash)``, a value committed somewhere the attacker cannot also rewrite, to catch
+    truncation and whole-chain forgery.
+    """
+    problems: List[str] = []
+    prev: str = GENESIS
+    for i, entry in enumerate(entries):
+        seq = entry.get("seq")
+        if seq != i:
+            problems.append(f"entry {i} (seq {seq}): out of order or gap - seq != position")
+        if entry.get("prev_hash") != prev:
+            problems.append(f"entry {i} (seq {seq}): broken link - prev_hash does not match")
+        if entry.get("hash") != _digest(entry):
+            problems.append(f"entry {i} (seq {seq}): content tampered - hash does not match")
+        prev = entry.get("hash") or ""
+    if expected_head is not None:
+        count, last_hash = expected_head
+        if len(entries) != count:
+            problems.append(
+                f"length mismatch: {len(entries)} entries, anchor expects {count} (possible truncation)"
+            )
+        actual_head = entries[-1].get("hash") if entries else GENESIS
+        if actual_head != last_hash:
+            problems.append("head mismatch: last hash does not match the external anchor")
+    return (not problems), problems
+
+
+def verify_file(path: str) -> Tuple[bool, List[str]]:
+    """Convenience: load a JSONL audit file and verify its chain."""
+    return verify(load(path))

recusal/checks.py

@@ -0,0 +1,242 @@
+"""
+Built-in deterministic checks, turn data into evidence.
+
+The verdict kernel (``compute_verdict``) decides; these functions do the tedious
+part that earns the decision: inspect real data and emit findings. Each check
+takes a materialized sequence of dict-like rows (a ``list`` of dicts, JSON records,
+or pandas rows, anything with ``[]`` access and a length). Iterators such as a
+generator or ``csv.DictReader`` must be wrapped first: ``list(csv.DictReader(f))``.
+Each check returns a single ``Finding`` ready to hand to ``compute_verdict``.
+
+Severity is a parameter, not a hardcode, *you* decide whether a high null rate
+is a CRITICAL stop or a WARNING. Pure logic, standard library only, no pandas
+required.
+
+Typical use::
+
+    from recusal import compute_verdict
+    from recusal.checks import row_count, null_rate, referential_integrity
+
+    findings = [
+        row_count(users, min_rows=1),
+        null_rate(users, "email", max_rate=0.10),
+        referential_integrity(orders, users, fk="user_id", pk="id"),
+    ]
+    verdict = compute_verdict(findings)   # PASS / RETRY / FAIL
+"""
+
+from typing import Any, Iterable, Sequence
+
+from .evidence import Finding, RuleSeverity
+
+Rows = Sequence[Any]  # each row supports row["column"]
+
+
+def _passed(check_type: str, severity: str, message: str, **context: Any) -> Finding:
+    return Finding.ok(check_type, severity=severity, message=message, **context)
+
+
+def _failed(check_type: str, severity: str, message: str, **context: Any) -> Finding:
+    return Finding.fail(check_type, severity=severity, message=message, **context)
+
+
+def row_count(
+    rows: Rows,
+    min_rows: int = 1,
+    severity: str = RuleSeverity.CRITICAL.value,
+    label: str = "dataset",
+) -> Finding:
+    """Fail if there are fewer than ``min_rows`` rows (empty data usually means
+    generation silently failed)."""
+    n = len(rows)
+    if n < min_rows:
+        return _failed(
+            "row_count",
+            severity,
+            f"{label}: {n} rows < required {min_rows}.",
+            actual=n,
+            min_rows=min_rows,
+            label=label,
+        )
+    return _passed("row_count", severity, f"{label}: {n} rows.", actual=n, label=label)
+
+
+def null_rate(
+    rows: Rows,
+    column: str,
+    max_rate: float = 0.15,
+    severity: str = RuleSeverity.ERROR.value,
+) -> Finding:
+    """Fail if the fraction of null/empty values in ``column`` exceeds ``max_rate``."""
+    total = len(rows)
+    if total == 0:
+        return _passed("null_rate", severity, f"{column}: no rows to check.", column=column)
+    nulls = sum(1 for r in rows if _is_null(_get(r, column)))
+    rate = nulls / total
+    if rate > max_rate:
+        return _failed(
+            "null_rate",
+            severity,
+            f"{column}: null rate {rate:.1%} > max {max_rate:.1%} ({nulls}/{total}).",
+            column=column,
+            null_rate=rate,
+            max_rate=max_rate,
+        )
+    return _passed(
+        "null_rate",
+        severity,
+        f"{column}: null rate {rate:.1%} within {max_rate:.1%}.",
+        column=column,
+        null_rate=rate,
+    )
+
+
+def referential_integrity(
+    child_rows: Rows,
+    parent_rows: Rows,
+    fk: str,
+    pk: str,
+    severity: str = RuleSeverity.CRITICAL.value,
+) -> Finding:
+    """Fail if any child row's foreign key has no matching parent primary key
+    (orphans = broken relationships)."""
+    parent_keys = {_get(r, pk) for r in parent_rows}
+    orphans = [
+        _get(r, fk)
+        for r in child_rows
+        if not _is_null(_get(r, fk)) and _get(r, fk) not in parent_keys
+    ]
+    if orphans:
+        sample = ", ".join(str(o) for o in orphans[:5])
+        return _failed(
+            "referential_integrity",
+            severity,
+            f"{len(orphans)} orphan(s) in {fk} -> {pk} (e.g. {sample}).",
+            fk=fk,
+            pk=pk,
+            orphan_count=len(orphans),
+        )
+    return _passed(
+        "referential_integrity",
+        severity,
+        f"{fk} -> {pk}: no orphans.",
+        fk=fk,
+        pk=pk,
+        orphan_count=0,
+    )
+
+
+def in_set(
+    rows: Rows,
+    column: str,
+    allowed: Iterable[Any],
+    severity: str = RuleSeverity.ERROR.value,
+) -> Finding:
+    """Fail if any non-null value in ``column`` is outside the ``allowed`` set."""
+    allowed_set = set(allowed)
+    bad = [
+        _get(r, column)
+        for r in rows
+        if not _is_null(_get(r, column)) and _get(r, column) not in allowed_set
+    ]
+    if bad:
+        sample = ", ".join(str(b) for b in sorted(set(map(str, bad)))[:5])
+        return _failed(
+            "in_set",
+            severity,
+            f"{column}: {len(bad)} value(s) not in approved set (e.g. {sample}).",
+            column=column,
+            violation_count=len(bad),
+        )
+    return _passed("in_set", severity, f"{column}: all values in approved set.", column=column)
+
+
+def in_range(
+    rows: Rows,
+    column: str,
+    min_value: float,
+    max_value: float,
+    severity: str = RuleSeverity.ERROR.value,
+) -> Finding:
+    """Fail if any numeric value in ``column`` falls outside [min_value, max_value]."""
+    violations = 0
+    for r in rows:
+        v = _get(r, column)
+        if _is_null(v):
+            continue
+        try:
+            fv = float(v)
+        except (TypeError, ValueError):
+            violations += 1
+            continue
+        if fv < min_value or fv > max_value:
+            violations += 1
+    if violations:
+        return _failed(
+            "in_range",
+            severity,
+            f"{column}: {violations} value(s) outside [{min_value}, {max_value}].",
+            column=column,
+            violation_count=violations,
+        )
+    return _passed(
+        "in_range",
+        severity,
+        f"{column}: all values within [{min_value}, {max_value}].",
+        column=column,
+    )
+
+
+def required_keys(
+    rows: Rows,
+    keys: Iterable[str],
+    severity: str = RuleSeverity.CRITICAL.value,
+) -> Finding:
+    """Fail if any row is missing one of the required ``keys`` (schema drift)."""
+    required = list(keys)
+    missing_rows = 0
+    seen_missing: set = set()
+    for r in rows:
+        absent = [k for k in required if not _has(r, k)]
+        if absent:
+            missing_rows += 1
+            seen_missing.update(absent)
+    if missing_rows:
+        cols = ", ".join(sorted(seen_missing))
+        return _failed(
+            "required_keys",
+            severity,
+            f"{missing_rows} row(s) missing required key(s): {cols}.",
+            missing_keys=sorted(seen_missing),
+            affected_rows=missing_rows,
+        )
+    return _passed(
+        "required_keys", severity, f"all rows have required keys: {', '.join(required)}."
+    )
+
+
+# ── tiny accessors that work for dicts and pandas-like rows ────────────────────
+
+
+def _get(row: Any, key: str) -> Any:
+    try:
+        return row[key]
+    except (KeyError, IndexError, TypeError, AttributeError):
+        return getattr(row, key, None)
+
+
+def _has(row: Any, key: str) -> bool:
+    try:
+        row[key]
+        return True
+    except (KeyError, IndexError, TypeError, AttributeError):
+        return hasattr(row, key)
+
+
+def _is_null(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str) and value.strip() == "":
+        return True
+    # NaN is the only value not equal to itself.
+    return value != value

recusal/classify.py

@@ -0,0 +1,207 @@
+"""
+Deterministic failure classification + routing.
+
+When an agent's action or output fails, the next move depends on *what kind* of
+failure it is: a transient hiccup (retry), a policy refusal (don't retry as-is),
+injected instructions in tool output (quarantine), a code bug (fix the code), the
+wrong data shape (re-shape), missing data (fetch), or an ambiguous request
+(ask a human). Guessing wastes a retry; asking a model is non-deterministic.
+
+``classify_failure`` decides by explicit marker rules, same input, same class,
+same route, every time. It ships a default taxonomy (extracted from a real
+autonomous build system and generalized) that you can extend or replace.
+
+Pure logic, standard library only.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from .evidence import Verdict
+
+
+@dataclass(frozen=True)
+class FailureClass:
+    """One category of failure and where it routes.
+
+    ``markers`` are case-insensitive substrings that signal this class; ``route`` is
+    the remediation channel/action a downstream system acts on (e.g. ``"retry"``,
+    ``"fix-code"``, ``"ask-human"``).
+    """
+
+    name: str
+    route: str
+    markers: Sequence[str]
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The class a failure was assigned and how it routes."""
+
+    failure_class: str
+    route: str
+    marker: Optional[str]  # the marker that matched, or None if it fell through
+    message: str
+
+    @property
+    def matched(self) -> bool:
+        return self.marker is not None
+
+
+# Order matters: the most specific / security-critical classes come first so a
+# policy refusal or an injection is never misread as a generic code/data error.
+DEFAULT_TAXONOMY: Sequence[FailureClass] = (
+    FailureClass(
+        "policy_violation",
+        "refuse",
+        (
+            "refused by the gate",
+            "recusal refused",
+            "subject guard",
+            "blocked by policy",
+            "permission denied",
+        ),
+        "An action a deterministic policy refused, do not retry as-is; escalate or change the plan.",
+    ),
+    FailureClass(
+        "prompt_injection",
+        "quarantine",
+        (
+            "ignore previous instructions",
+            "disregard the above",
+            "ignore the system prompt",
+            "exfiltrate",
+            "send the api key",
+        ),
+        "Tool output appears to carry injected instructions, quarantine, don't act on it.",
+    ),
+    FailureClass(
+        "transient",
+        "retry",
+        (
+            "timed out",
+            "timeout",
+            "rate limit",
+            "too many requests",
+            "connection reset",
+            "econnreset",
+            "temporarily unavailable",
+            "service unavailable",
+        ),
+        "A recoverable infrastructure hiccup, retry with backoff.",
+    ),
+    FailureClass(
+        "code_bug",
+        "fix-code",
+        (
+            "traceback",
+            "syntaxerror",
+            "nameerror",
+            "typeerror",
+            "attributeerror",
+            "assertionerror",
+            "modulenotfounderror",
+            "importerror",
+            "no module named",
+            "command not found",
+            "compile error",
+            "exit code 1",
+            "test failed",
+            "tests failed",
+        ),
+        "The generated code is wrong, route to the builder/coding agent.",
+    ),
+    FailureClass(
+        "data_shape",
+        "fix-data",
+        (
+            "schema mismatch",
+            "invalid type",
+            "column not found",
+            "unexpected field",
+            "validation error",
+            "null rate",
+            "keyerror",
+        ),
+        "Data is the wrong shape, re-synthesize or re-shape it.",
+    ),
+    FailureClass(
+        "data_missing",
+        "fetch-data",
+        (
+            "0 rows",
+            "no rows",
+            "empty result",
+            "not found",
+            "does not exist",
+            "orphan",
+            "missing data",
+        ),
+        "Expected data is absent, fetch or re-migrate it.",
+    ),
+    FailureClass(
+        "spec_ambiguity",
+        "ask-human",
+        (
+            "ambiguous",
+            "unclear",
+            "underspecified",
+            "which record",
+            "did you mean",
+            "need clarification",
+            "acceptance criteria",
+        ),
+        "The request is ambiguous, escalate to a human for refinement.",
+    ),
+)
+
+
+def classify_failure(
+    text: str,
+    *,
+    taxonomy: Sequence[FailureClass] = DEFAULT_TAXONOMY,
+    fallback_class: str = "unknown",
+    fallback_route: str = "ask-human",
+) -> Classification:
+    """Classify a failure (an error string, a verdict reason, a log line) and route it.
+
+    First matching class wins (taxonomy order is precedence). If nothing matches,
+    returns the fallback class/route, never guesses. Non-string input is coerced with
+    ``str()`` so the router never raises on the wrong type.
+    """
+    haystack = str(text or "").lower()
+    for fc in taxonomy:
+        for marker in fc.markers:
+            if marker.lower() in haystack:
+                return Classification(
+                    fc.name,
+                    fc.route,
+                    marker,
+                    f"{fc.name} -> {fc.route} (matched '{marker}')",
+                )
+    return Classification(
+        fallback_class,
+        fallback_route,
+        None,
+        f"unclassified -> {fallback_route}",
+    )
+
+
+def classify_verdict(
+    verdict: Verdict,
+    *,
+    taxonomy: Sequence[FailureClass] = DEFAULT_TAXONOMY,
+    fallback_class: str = "unknown",
+    fallback_route: str = "ask-human",
+) -> Classification:
+    """Classify a non-PASS ``Verdict`` from its reasons, what kind of failure, and where it
+    goes. A PASS verdict has nothing to route, so it returns ``pass -> proceed``."""
+    if verdict.passed:
+        return Classification("pass", "proceed", None, "verdict passed; nothing to route")
+    return classify_failure(
+        verdict.reasons(),
+        taxonomy=taxonomy,
+        fallback_class=fallback_class,
+        fallback_route=fallback_route,
+    )