evidencebound-core 0.4.0__py3-none-any.whl

evidencebound/__init__.py

@@ -0,0 +1,105 @@
+"""EvidenceBound public API."""
+from .api import EvidenceBound
+from .canonical import CANONICALIZATION_VERSION, CanonicalizationError, canonical_bytes, digest
+from .events import Event, EventSink, ListEventSink, NullEventSink
+from .graph import DependencyGraph, GraphError
+from .models import (
+    ActionDecision,
+    ApplicabilityStatus,
+    Checkpoint,
+    EvidenceAssessment,
+    EvidenceRecord,
+    EvidenceState,
+    IntegrityStatus,
+    InvalidationReason,
+    PolicyBinding,
+    ProofReceipt,
+    ProvenanceRecord,
+    VerificationResult,
+)
+from .persistence import (
+    PERSISTED_RECORD_VERSION,
+    PERSISTENCE_SCHEMA_VERSION,
+    PersistenceError,
+    PersistenceIntegrityError,
+    PersistenceStore,
+    UnsupportedPersistenceSchema,
+)
+from .recovery import RecoveryPlan, action_after_recovery, plan_recovery
+from .replay import ReplayConflict, ReplayGuard, ReplayStatus
+from .signing import (
+    KeyState,
+    ReceiptSigner,
+    ReceiptVerifier,
+    SignatureCheck,
+    SignatureCheckStatus,
+    SignedProofReceipt,
+    SignedReceiptStatus,
+    SignedReceiptVerification,
+    sign_receipt,
+    signed_receipt_bytes,
+    verify_signed_receipt,
+)
+from .verification import (
+    checkpoint_digest,
+    evidence_digest,
+    verify_checkpoint,
+    verify_receipt,
+    verify_verification_receipt,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "ActionDecision",
+    "ApplicabilityStatus",
+    "CANONICALIZATION_VERSION",
+    "CanonicalizationError",
+    "Checkpoint",
+    "DependencyGraph",
+    "EvidenceAssessment",
+    "EvidenceBound",
+    "EvidenceRecord",
+    "EvidenceState",
+    "Event",
+    "EventSink",
+    "GraphError",
+    "IntegrityStatus",
+    "InvalidationReason",
+    "KeyState",
+    "ListEventSink",
+    "NullEventSink",
+    "PERSISTED_RECORD_VERSION",
+    "PERSISTENCE_SCHEMA_VERSION",
+    "PersistenceError",
+    "PersistenceIntegrityError",
+    "PersistenceStore",
+    "PolicyBinding",
+    "ProofReceipt",
+    "ProvenanceRecord",
+    "ReceiptSigner",
+    "ReceiptVerifier",
+    "RecoveryPlan",
+    "ReplayConflict",
+    "ReplayGuard",
+    "ReplayStatus",
+    "SignatureCheck",
+    "SignatureCheckStatus",
+    "SignedProofReceipt",
+    "SignedReceiptStatus",
+    "SignedReceiptVerification",
+    "UnsupportedPersistenceSchema",
+    "VerificationResult",
+    "action_after_recovery",
+    "canonical_bytes",
+    "checkpoint_digest",
+    "digest",
+    "evidence_digest",
+    "plan_recovery",
+    "sign_receipt",
+    "signed_receipt_bytes",
+    "verify_checkpoint",
+    "verify_receipt",
+    "verify_signed_receipt",
+    "verify_verification_receipt",
+]

evidencebound/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .plain import GuardedRun, run_guarded
+
+__all__ = ["GuardedRun", "run_guarded"]

evidencebound/adapters/google_adk.py

@@ -0,0 +1,71 @@
+"""Dependency-free integration seam for Google ADK agent callbacks.
+
+Google ADK's tested callback contract invokes ``after_agent_callback`` with a
+single keyword argument named ``callback_context``. EvidenceBound does not import
+ADK; callers provide functions that extract evidence and the protected output from
+that context (commonly from ADK state populated through ``output_key``).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from ..api import EvidenceBound
+from ..models import ActionDecision, EvidenceRecord, VerificationResult
+
+EvidenceFactory = Callable[[Any], list[EvidenceRecord]]
+OutputFactory = Callable[[Any], object]
+DEFAULT_ADK_STATE_KEY = "evidencebound.verification"
+
+
+def adk_consequential_action_allowed(
+    state: object,
+    *,
+    state_key: str = DEFAULT_ADK_STATE_KEY,
+) -> bool:
+    """Return True only for an explicit serialized EvidenceBound ``ALLOW`` result.
+
+    The helper deliberately treats missing, malformed or incomplete callback state
+    as blocked. It does not infer approval from an ADK response event or from agent
+    completion alone.
+    """
+    if not isinstance(state, Mapping):
+        return False
+    result = state.get(state_key)
+    if not isinstance(result, Mapping):
+        return False
+    return result.get("action") == ActionDecision.ALLOW.value
+
+
+@dataclass(slots=True)
+class AdkCallbackAdapter:
+    """Callable-compatible ADK after-agent adapter without an ADK dependency.
+
+    Register ``adapter.after_agent`` as ``after_agent_callback``. The method
+    returns ``None`` so it does not replace the agent response. It stores the
+    structured EvidenceBound verification in ``callback_context.state`` when
+    that object exposes a mutable mapping-like ``state`` attribute.
+    """
+
+    evidencebound: EvidenceBound
+    evidence_factory: EvidenceFactory
+    output_factory: OutputFactory
+    agent_name: str
+    state_key: str = DEFAULT_ADK_STATE_KEY
+    last_verification: VerificationResult | None = None
+
+    def after_agent(self, callback_context: Any) -> None:
+        evidence = self.evidence_factory(callback_context)
+        output = self.output_factory(callback_context)
+        checkpoint = self.evidencebound.checkpoint(
+            agent=self.agent_name,
+            evidence=evidence,
+            output=output,
+        )
+        result = self.evidencebound.verify(checkpoint)
+        self.last_verification = result
+        state = getattr(callback_context, "state", None)
+        if state is not None:
+            state[self.state_key] = result.to_dict()
+        return None

evidencebound/adapters/plain.py

@@ -0,0 +1,37 @@
+"""Thin framework-neutral hook adapter."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from ..api import EvidenceBound
+from ..models import Checkpoint, EvidenceRecord, VerificationResult
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class GuardedRun(Generic[T]):
+    value: T
+    checkpoint: Checkpoint
+    verification: VerificationResult
+
+
+def run_guarded(
+    eb: EvidenceBound,
+    *,
+    agent: str,
+    evidence: list[EvidenceRecord],
+    worker: Callable[[], T],
+    depends_on: tuple[str, ...] = (),
+) -> GuardedRun[T]:
+    value = worker()
+    checkpoint = eb.checkpoint(
+        agent=agent,
+        evidence=evidence,
+        output=value,
+        depends_on=depends_on,
+    )
+    verification = eb.verify(checkpoint)
+    return GuardedRun(value, checkpoint, verification)

evidencebound/api.py

@@ -0,0 +1,138 @@
+"""High-level EvidenceBound facade."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+
+from .canonical import digest
+from .events import Event, EventSink, NullEventSink
+from .graph import DependencyGraph
+from .models import (
+    ActionDecision,
+    Checkpoint,
+    EvidenceRecord,
+    InvalidationReason,
+    PolicyBinding,
+    ProofReceipt,
+    VerificationResult,
+)
+from .recovery import RecoveryPlan, plan_recovery
+from .verification import verify_checkpoint
+
+
+class EvidenceBound:
+    def __init__(self, *, policy: PolicyBinding, event_sink: EventSink | None = None) -> None:
+        self.policy = policy
+        self.events = event_sink or NullEventSink()
+        self._checkpoints: dict[str, Checkpoint] = {}
+        self._verification: dict[str, VerificationResult] = {}
+
+    def checkpoint(
+        self,
+        *,
+        agent: str,
+        evidence: list[EvidenceRecord] | tuple[EvidenceRecord, ...],
+        output: object,
+        depends_on: list[str] | tuple[str, ...] = (),
+        checkpoint_id: str | None = None,
+        operation_id: str | None = None,
+    ) -> Checkpoint:
+        if checkpoint_id is None:
+            checkpoint_id = digest(
+                {
+                    "agent": agent,
+                    "evidence": [record.to_dict() for record in evidence],
+                    "output": output,
+                    "depends_on": list(depends_on),
+                    "policy": self.policy.to_dict(),
+                    "operation_id": operation_id,
+                },
+                domain="checkpoint-id",
+            )[:24]
+        if checkpoint_id in self._checkpoints:
+            raise ValueError(f"duplicate checkpoint id: {checkpoint_id}")
+        evidence_ids = [record.evidence_id for record in evidence]
+        if len(evidence_ids) != len(set(evidence_ids)):
+            raise ValueError("duplicate evidence ids are not allowed")
+        missing = sorted(set(depends_on) - set(self._checkpoints))
+        if missing:
+            raise ValueError(f"unknown dependencies: {missing}")
+        checkpoint = Checkpoint(
+            checkpoint_id,
+            agent,
+            tuple(evidence),
+            output,  # type: ignore[arg-type]
+            self.policy,
+            tuple(depends_on),
+            operation_id,
+        )
+        self._checkpoints[checkpoint_id] = checkpoint
+        self.events.emit(
+            Event("checkpoint_created", {"checkpoint_id": checkpoint_id, "agent": agent})
+        )
+        return checkpoint
+
+    def verify(
+        self,
+        checkpoint: Checkpoint,
+        *,
+        current_evidence: Mapping[str, EvidenceRecord] | None = None,
+        expected_policy: PolicyBinding | None = None,
+        prior_receipt: ProofReceipt | None = None,
+        now: datetime | None = None,
+    ) -> VerificationResult:
+        result = verify_checkpoint(
+            checkpoint,
+            current_evidence=current_evidence,
+            expected_policy=expected_policy or self.policy,
+            prior_receipt=prior_receipt,
+            now=now,
+        )
+        self._verification[checkpoint.checkpoint_id] = result
+        self.events.emit(Event("verification_completed", {
+            "checkpoint_id": checkpoint.checkpoint_id,
+            "action": result.action.value,
+            "applicability": result.applicability.value,
+        }))
+        if result.integrity.value == "FAILED":
+            self.events.emit(Event("integrity_failed", {"checkpoint_id": checkpoint.checkpoint_id}))
+        if result.action is not ActionDecision.ALLOW:
+            self.events.emit(Event("action_blocked", {
+                "checkpoint_id": checkpoint.checkpoint_id,
+                "decision": result.action.value,
+            }))
+        return result
+
+    def graph(self) -> DependencyGraph:
+        return DependencyGraph(self._checkpoints.values())
+
+    def invalidate(
+        self,
+        *,
+        checkpoint_id: str,
+        reason: InvalidationReason,
+        consequential: set[str] | None = None,
+    ) -> RecoveryPlan:
+        self.events.emit(Event("invalidation_started", {
+            "checkpoint_id": checkpoint_id,
+            "reason": reason.value,
+        }))
+        graph = self.graph()
+        affected = graph.blast_radius([checkpoint_id])
+        self.events.emit(Event("blast_radius_computed", {
+            "checkpoint_id": checkpoint_id,
+            "affected": list(affected),
+        }))
+        plan = plan_recovery(
+            graph,
+            {checkpoint_id: reason},
+            verification=self._verification,
+            consequential=consequential,
+        )
+        self.events.emit(Event("recovery_planned", {
+            "recompute": list(plan.recompute),
+            "reusable": list(plan.reusable),
+            "requires_verification": list(plan.requires_verification),
+            "blocked": list(plan.blocked),
+        }))
+        return plan

evidencebound/canonical.py

@@ -0,0 +1,49 @@
+"""Versioned deterministic canonicalization used by EvidenceBound receipts."""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+CANONICALIZATION_VERSION = "EBCJ-1"
+
+
+class CanonicalizationError(ValueError):
+    """Raised when a value cannot be represented unambiguously by EBCJ-1."""
+
+
+def _validate(value: Any, path: str = "$") -> None:
+    if value is None or isinstance(value, (bool, int, str)):
+        return
+    if isinstance(value, float):
+        raise CanonicalizationError(f"floats are not supported by EBCJ-1 at {path}")
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise CanonicalizationError(f"mapping key is not a string at {path}")
+            _validate(item, f"{path}.{key}")
+        return
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        for index, item in enumerate(value):
+            _validate(item, f"{path}[{index}]")
+        return
+    raise CanonicalizationError(f"unsupported type {type(value).__name__} at {path}")
+
+
+def canonical_bytes(value: Any) -> bytes:
+    """Return deterministic UTF-8 JSON bytes for the intentionally narrow EBCJ-1 domain."""
+    _validate(value)
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def digest(value: Any, *, domain: str) -> str:
+    """SHA-256 digest with versioned domain separation."""
+    prefix = f"evidencebound:{domain}:{CANONICALIZATION_VERSION}\0".encode()
+    return hashlib.sha256(prefix + canonical_bytes(value)).hexdigest()

evidencebound/events.py

@@ -0,0 +1,28 @@
+"""Provider-neutral structured event hooks."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    name: str
+    attributes: dict[str, Any]
+
+
+class EventSink(Protocol):
+    def emit(self, event: Event) -> None: ...
+
+
+class NullEventSink:
+    def emit(self, event: Event) -> None:
+        return None
+
+
+class ListEventSink:
+    def __init__(self) -> None:
+        self.events: list[Event] = []
+
+    def emit(self, event: Event) -> None:
+        self.events.append(event)

evidencebound/graph.py

@@ -0,0 +1,110 @@
+"""Deterministic dependency graph with exact blast-radius traversal."""
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from collections.abc import Iterable
+
+from .models import Checkpoint
+
+
+class GraphError(ValueError):
+    pass
+
+
+class DependencyGraph:
+    def __init__(self, checkpoints: Iterable[Checkpoint] = ()) -> None:
+        self._nodes: dict[str, Checkpoint] = {}
+        for checkpoint in checkpoints:
+            if checkpoint.checkpoint_id in self._nodes:
+                raise GraphError(f"duplicate checkpoint id: {checkpoint.checkpoint_id}")
+            self._nodes[checkpoint.checkpoint_id] = checkpoint
+        self._validate_dependencies()
+        self._validate_acyclic()
+
+    @property
+    def checkpoint_ids(self) -> tuple[str, ...]:
+        return tuple(sorted(self._nodes))
+
+    def _validate_dependencies(self) -> None:
+        for checkpoint in self._nodes.values():
+            for dependency in checkpoint.depends_on:
+                if dependency not in self._nodes:
+                    raise GraphError(
+                        f"checkpoint {checkpoint.checkpoint_id} depends on missing {dependency}"
+                    )
+
+    def _children(self) -> dict[str, set[str]]:
+        children: dict[str, set[str]] = defaultdict(set)
+        for checkpoint in self._nodes.values():
+            for dependency in checkpoint.depends_on:
+                children[dependency].add(checkpoint.checkpoint_id)
+        return children
+
+    def _validate_acyclic(self) -> None:
+        self.topological_order()
+
+    def topological_order(self) -> tuple[str, ...]:
+        indegree = {node: 0 for node in self._nodes}
+        children = self._children()
+        for checkpoint in self._nodes.values():
+            indegree[checkpoint.checkpoint_id] = len(checkpoint.depends_on)
+        ready = deque(sorted(node for node, degree in indegree.items() if degree == 0))
+        result: list[str] = []
+        while ready:
+            node = ready.popleft()
+            result.append(node)
+            for child in sorted(children.get(node, ())):
+                indegree[child] -= 1
+                if indegree[child] == 0:
+                    ready.append(child)
+            if len(ready) > 1:
+                ready = deque(sorted(ready))
+        if len(result) != len(self._nodes):
+            raise GraphError("dependency graph contains a cycle")
+        return tuple(result)
+
+    def descendants(self, checkpoint_id: str) -> tuple[str, ...]:
+        if checkpoint_id not in self._nodes:
+            raise GraphError(f"unknown checkpoint: {checkpoint_id}")
+        children = self._children()
+        seen: set[str] = set()
+        queue = deque(sorted(children.get(checkpoint_id, ())))
+        while queue:
+            current = queue.popleft()
+            if current in seen:
+                continue
+            seen.add(current)
+            queue.extend(sorted(children.get(current, ())))
+        order = self.topological_order()
+        return tuple(node for node in order if node in seen)
+
+    def ancestors(self, checkpoint_id: str) -> tuple[str, ...]:
+        if checkpoint_id not in self._nodes:
+            raise GraphError(f"unknown checkpoint: {checkpoint_id}")
+        seen: set[str] = set()
+        queue = deque(sorted(self._nodes[checkpoint_id].depends_on))
+        while queue:
+            current = queue.popleft()
+            if current in seen:
+                continue
+            seen.add(current)
+            queue.extend(sorted(self._nodes[current].depends_on))
+        order = self.topological_order()
+        return tuple(node for node in order if node in seen)
+
+    def blast_radius(self, checkpoint_ids: Iterable[str]) -> tuple[str, ...]:
+        roots = set(checkpoint_ids)
+        for root in roots:
+            if root not in self._nodes:
+                raise GraphError(f"unknown checkpoint: {root}")
+        affected = set(roots)
+        for root in roots:
+            affected.update(self.descendants(root))
+        order = self.topological_order()
+        return tuple(node for node in order if node in affected)
+
+    def get(self, checkpoint_id: str) -> Checkpoint:
+        try:
+            return self._nodes[checkpoint_id]
+        except KeyError as exc:
+            raise GraphError(f"unknown checkpoint: {checkpoint_id}") from exc