hapax-agentgov 0.2.0__py3-none-any.whl

agentgov/__init__.py

@@ -0,0 +1,104 @@
+"""agentgov — Computational constitutional governance for AI agent systems.
+
+Pure governance logic with algebraic guarantees:
+- ConsentLabel: join-semilattice (associative, commutative, idempotent)
+- Labeled[T]: functor (identity, composition)
+- Principal: non-amplification (bound <= delegator authority)
+- Governor: consistent with can_flow_to
+- ProvenanceExpr: PosBool(X) semiring
+- VetoChain: deny-wins composition
+- Says: DCC-style principal attribution monad
+"""
+
+from agentgov.agent_governor import create_agent_governor
+from agentgov.carrier import CarrierFact, CarrierRegistry, DisplacementResult
+from agentgov.consent import ConsentContract, ConsentRegistry, load_contracts
+from agentgov.consent_label import ConsentLabel
+from agentgov.governor import (
+    GovernorDenial,
+    GovernorPolicy,
+    GovernorResult,
+    GovernorWrapper,
+    consent_input_policy,
+    consent_output_policy,
+)
+from agentgov.hooks import (
+    HookResult,
+    scan_attribution_entities,
+    scan_management_boundary,
+    scan_pii,
+    scan_provenance_references,
+    scan_single_user_violations,
+    validate_all,
+)
+from agentgov.labeled import Labeled
+from agentgov.primitives import (
+    Candidate,
+    FallbackChain,
+    GatedResult,
+    Selected,
+    Veto,
+    VetoChain,
+    VetoResult,
+)
+from agentgov.principal import Principal, PrincipalKind
+from agentgov.provenance import ProvenanceExpr
+from agentgov.revocation import (
+    PurgeResult,
+    RevocationPropagator,
+    RevocationReport,
+    check_provenance,
+)
+from agentgov.says import Says
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Principal model
+    "Principal",
+    "PrincipalKind",
+    # Consent
+    "ConsentContract",
+    "ConsentRegistry",
+    "ConsentLabel",
+    "load_contracts",
+    # Labeled data
+    "Labeled",
+    # Provenance
+    "ProvenanceExpr",
+    # Carrier dynamics
+    "CarrierFact",
+    "CarrierRegistry",
+    "DisplacementResult",
+    # Governor
+    "GovernorWrapper",
+    "GovernorPolicy",
+    "GovernorResult",
+    "GovernorDenial",
+    "consent_input_policy",
+    "consent_output_policy",
+    "create_agent_governor",
+    # Revocation cascade
+    "RevocationPropagator",
+    "RevocationReport",
+    "PurgeResult",
+    "check_provenance",
+    # Compositional primitives
+    "Candidate",
+    "FallbackChain",
+    "GatedResult",
+    "Selected",
+    "Veto",
+    "VetoChain",
+    "VetoResult",
+    # Says monad
+    "Says",
+    # Governance hooks
+    "HookResult",
+    "scan_pii",
+    "scan_single_user_violations",
+    "scan_attribution_entities",
+    "scan_provenance_references",
+    "scan_management_boundary",
+    "validate_all",
+]

agentgov/agent_governor.py

@@ -0,0 +1,129 @@
+"""Agent governor factory: builds GovernorWrapper from axiom bindings.
+
+Translates declarative axiom bindings in agent manifests into runtime
+governance policies. Each agent gets a GovernorWrapper configured with
+input/output policies derived from its axiom relationships.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from agentgov.consent_label import ConsentLabel
+from agentgov.governor import (
+    GovernorPolicy,
+    GovernorWrapper,
+    consent_input_policy,
+    consent_output_policy,
+)
+from agentgov.labeled import Labeled
+
+_log = logging.getLogger(__name__)
+
+PolicyBuilder = Callable[[str], tuple[list[GovernorPolicy], list[GovernorPolicy]]]
+
+
+def interpersonal_transparency_policies(
+    role: str,
+) -> tuple[list[GovernorPolicy], list[GovernorPolicy]]:
+    """Build policies for the interpersonal_transparency axiom."""
+    input_policies: list[GovernorPolicy] = []
+    output_policies: list[GovernorPolicy] = []
+
+    if role in ("subject", "enforcer"):
+        input_policies.append(consent_input_policy(ConsentLabel.bottom()))
+        output_policies.append(consent_output_policy(ConsentLabel.bottom()))
+
+    return input_policies, output_policies
+
+
+def corporate_boundary_policies(
+    role: str,
+) -> tuple[list[GovernorPolicy], list[GovernorPolicy]]:
+    """Build policies for the corporate_boundary axiom."""
+    input_policies: list[GovernorPolicy] = []
+    output_policies: list[GovernorPolicy] = []
+
+    if role in ("subject", "enforcer"):
+
+        def _no_work_data(_agent_id: str, data: Labeled[Any]) -> bool:
+            if not (hasattr(data, "metadata") and isinstance(data.metadata, dict)):
+                _log.warning("corporate_boundary: denying data with no metadata dict (fail-closed)")
+                return False
+            category = data.metadata.get("data_category")
+            if category is None:
+                _log.warning(
+                    "corporate_boundary: denying data with no data_category key (fail-closed)"
+                )
+                return False
+            return category != "work"
+
+        output_policies.append(
+            GovernorPolicy(
+                name="corporate_boundary_output",
+                check=_no_work_data,
+                axiom_id="corporate_boundary",
+                description="Block work data from persisting to home system",
+            )
+        )
+
+    return input_policies, output_policies
+
+
+DEFAULT_AXIOM_BUILDERS: dict[str, PolicyBuilder] = {
+    "interpersonal_transparency": interpersonal_transparency_policies,
+    "corporate_boundary": corporate_boundary_policies,
+}
+
+
+def create_agent_governor(
+    agent_id: str,
+    axiom_bindings: list[dict[str, Any]] | None = None,
+    *,
+    axiom_builders: dict[str, PolicyBuilder] | None = None,
+    binding_loader: Callable[[str], list[Any]] | None = None,
+) -> GovernorWrapper:
+    """Build a GovernorWrapper from agent manifest axiom bindings.
+
+    Args:
+        agent_id: Agent identifier.
+        axiom_bindings: List of binding dicts with keys 'axiom_id', 'role'.
+        axiom_builders: Custom axiom-to-policy mapping. Defaults to
+            built-in interpersonal_transparency and corporate_boundary.
+        binding_loader: Optional callable to load bindings from an
+            external registry when axiom_bindings is None.
+    """
+    gov = GovernorWrapper(agent_id)
+    builders = axiom_builders or DEFAULT_AXIOM_BUILDERS
+
+    bindings = axiom_bindings
+    if bindings is None and binding_loader is not None:
+        bindings = binding_loader(agent_id)
+    if bindings is None:
+        bindings = []
+
+    for binding in bindings:
+        axiom_id = binding.get("axiom_id", "") if isinstance(binding, dict) else binding.axiom_id
+        role = binding.get("role", "subject") if isinstance(binding, dict) else binding.role
+
+        builder = builders.get(axiom_id)
+        if builder is None:
+            continue
+
+        input_policies, output_policies = builder(role)
+        for p in input_policies:
+            gov.add_input_policy(p)
+        for p in output_policies:
+            gov.add_output_policy(p)
+
+        _log.debug(
+            "Governor %s: added %d input + %d output policies for %s",
+            agent_id,
+            len(input_policies),
+            len(output_policies),
+            axiom_id,
+        )
+
+    return gov

agentgov/carrier.py

@@ -0,0 +1,138 @@
+"""Epistemic carrier dynamics: bounded cross-domain fact carrying.
+
+Each agent carries a small set of foreign-domain facts observed
+incidentally through contact topology. Carrier facts are Labeled[Any]
+values — consent labels travel with carried facts via the DLM join.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from agentgov.consent_label import ConsentLabel
+from agentgov.labeled import Labeled
+
+
+@dataclass(frozen=True)
+class CarrierFact:
+    """A foreign-domain fact carried incidentally by an agent."""
+
+    labeled: Labeled[Any]
+    source_domain: str
+    observation_count: int = 1
+    first_seen: float = 0.0
+    last_seen: float = 0.0
+
+    def observe(self, timestamp: float) -> CarrierFact:
+        """Return a new instance with incremented count and updated last_seen."""
+        return CarrierFact(
+            labeled=self.labeled,
+            source_domain=self.source_domain,
+            observation_count=self.observation_count + 1,
+            first_seen=self.first_seen,
+            last_seen=timestamp,
+        )
+
+    def same_fact(self, other: CarrierFact) -> bool:
+        """Check if two carrier facts represent the same observation."""
+        return (
+            self.labeled.value == other.labeled.value and self.source_domain == other.source_domain
+        )
+
+    @property
+    def consent_label(self) -> ConsentLabel:
+        return self.labeled.label
+
+    @property
+    def provenance(self) -> frozenset[str]:
+        return self.labeled.provenance
+
+
+@dataclass(frozen=True)
+class DisplacementResult:
+    """Outcome of offering a carrier fact to a registry."""
+
+    inserted: bool
+    displaced: CarrierFact | None = None
+    reason: str = ""
+
+
+class CarrierRegistry:
+    """Mutable registry of carrier facts per principal.
+
+    Enforces bounded capacity per principal. Displacement follows
+    frequency-weighted policy: new facts must be observed significantly
+    more frequently than the least-observed existing fact to displace it.
+    """
+
+    __slots__ = ("_slots", "_capacities", "displacement_threshold")
+
+    def __init__(self, displacement_threshold: float = 2.0) -> None:
+        self._slots: dict[str, list[CarrierFact]] = {}
+        self._capacities: dict[str, int] = {}
+        self.displacement_threshold = displacement_threshold
+
+    def register(self, principal_id: str, capacity: int) -> None:
+        if capacity < 0:
+            raise ValueError(f"Carrier capacity must be non-negative, got {capacity}")
+        self._slots.setdefault(principal_id, [])
+        self._capacities[principal_id] = capacity
+
+    def facts(self, principal_id: str) -> tuple[CarrierFact, ...]:
+        return tuple(self._slots.get(principal_id, []))
+
+    def offer(self, principal_id: str, fact: CarrierFact) -> DisplacementResult:
+        """Offer a carrier fact to a principal's slots."""
+        if principal_id not in self._capacities:
+            raise ValueError(f"Principal {principal_id} not registered")
+
+        slots = self._slots[principal_id]
+        capacity = self._capacities[principal_id]
+
+        for i, existing in enumerate(slots):
+            if existing.same_fact(fact):
+                slots[i] = existing.observe(fact.last_seen)
+                return DisplacementResult(inserted=True, reason="updated existing")
+
+        if len(slots) < capacity:
+            slots.append(fact)
+            return DisplacementResult(inserted=True, reason="slot available")
+
+        if not slots:
+            return DisplacementResult(inserted=False, reason="zero capacity")
+
+        least_idx = min(range(len(slots)), key=lambda i: slots[i].observation_count)
+        least = slots[least_idx]
+
+        if fact.observation_count > least.observation_count * self.displacement_threshold:
+            displaced = slots[least_idx]
+            slots[least_idx] = fact
+            return DisplacementResult(inserted=True, displaced=displaced, reason="displaced")
+
+        return DisplacementResult(
+            inserted=False,
+            reason=f"insufficient frequency: {fact.observation_count} <= "
+            f"{least.observation_count} * {self.displacement_threshold}",
+        )
+
+    def purge_by_provenance(self, contract_id: str) -> int:
+        """Remove carrier facts whose provenance includes contract_id."""
+        purged = 0
+        for slots in self._slots.values():
+            before = len(slots)
+            slots[:] = [f for f in slots if contract_id not in f.provenance]
+            purged += before - len(slots)
+        return purged
+
+
+def epistemic_contradiction_veto(
+    local_knowledge: Callable[[str, Any], bool],
+) -> Callable[[CarrierFact], bool]:
+    """Create a predicate that checks carrier facts against local knowledge."""
+
+    def _check(fact: CarrierFact) -> bool:
+        return local_knowledge(fact.source_domain, fact.labeled.value)
+
+    return _check

agentgov/consent.py

@@ -0,0 +1,316 @@
+"""Consent contract management for information flow governance.
+
+Provides contract loading, validation, and enforcement at data ingestion
+boundaries. Any data pathway handling person data must call
+contract_check() before persisting state.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+log = logging.getLogger(__name__)
+
+
+class ConsentContractLoadError(Exception):
+    """Raised when a contract YAML file fails to parse in strict mode."""
+
+
+@dataclass(frozen=True)
+class ConsentContract:
+    """A bilateral consent agreement between operator and subject.
+
+    Immutable once loaded. Revocation creates a new record, it does not
+    mutate the existing contract.
+    """
+
+    id: str
+    parties: tuple[str, str]
+    scope: frozenset[str]
+    direction: str = "one_way"
+    visibility_mechanism: str = "on_request"
+    created_at: str = ""
+    revoked_at: str | None = None
+    principal_class: str = ""
+    guardian: str | None = None
+
+    @property
+    def active(self) -> bool:
+        return self.revoked_at is None
+
+
+@dataclass
+class ConsentRegistry:
+    """Runtime registry of consent contracts.
+
+    Loaded from YAML files on disk. Provides contract_check() for
+    ingestion boundary enforcement.
+    """
+
+    _contracts: dict[str, ConsentContract] = field(default_factory=dict)
+    _fail_closed: bool = field(default=False)
+    _loaded_at: float = field(default=0.0)
+    _contracts_dir: Path | None = field(default=None)
+
+    @property
+    def fail_closed(self) -> bool:
+        return self._fail_closed
+
+    def is_stale(self, stale_threshold_s: float = 300.0) -> bool:
+        """Check if the registry was loaded too long ago to trust."""
+        if self._loaded_at == 0.0:
+            return False
+        return time.time() - self._loaded_at > stale_threshold_s
+
+    def load(self, contracts_dir: Path | None = None, *, strict: bool = False) -> int:
+        """Load all contract files from the contracts directory.
+
+        Args:
+            contracts_dir: Path to scan for YAML contract files.
+            strict: When True, raise ConsentContractLoadError on any
+                malformed YAML instead of logging and skipping.
+
+        Returns:
+            The number of active contracts loaded.
+        """
+        directory = contracts_dir or self._contracts_dir
+        if directory is None:
+            log.info("No contracts directory configured")
+            self._fail_closed = True
+            return 0
+
+        try:
+            if not directory.exists():
+                log.info("No contracts directory at %s", directory)
+                self._fail_closed = True
+                return 0
+
+            count = 0
+            for path in sorted(directory.glob("*.yaml")):
+                try:
+                    data = yaml.safe_load(path.read_text())
+                    if data is None:
+                        continue
+                    contract = parse_contract(data)
+                    self._contracts[contract.id] = contract
+                    if contract.active:
+                        count += 1
+                        log.info(
+                            "Loaded contract %s: %s <-> %s (scope: %s)",
+                            contract.id,
+                            contract.parties[0],
+                            contract.parties[1],
+                            ", ".join(sorted(contract.scope)),
+                        )
+                except Exception as exc:
+                    if strict:
+                        raise ConsentContractLoadError(
+                            f"Failed to load contract from {path}: {exc}"
+                        ) from exc
+                    log.exception("Failed to load contract from %s", path)
+
+            self._fail_closed = False
+            self._loaded_at = time.time()
+            return count
+        except ConsentContractLoadError:
+            raise
+        except Exception:
+            log.exception("Failed to load contracts from %s", directory)
+            self._fail_closed = True
+            return 0
+
+    def get(self, contract_id: str) -> ConsentContract | None:
+        return self._contracts.get(contract_id)
+
+    def __iter__(self):
+        return iter(self._contracts.values())
+
+    def contract_check(self, person_id: str, data_category: str) -> bool:
+        """Check whether an active contract permits this data flow.
+
+        Returns True if an active contract exists for the given person
+        with the given data category in scope. Returns False otherwise.
+        """
+        if self._fail_closed or self.is_stale():
+            return False
+        for contract in self._contracts.values():
+            if not contract.active:
+                continue
+            if person_id in contract.parties and data_category in contract.scope:
+                return True
+        return False
+
+    def get_contract_for(self, person_id: str) -> ConsentContract | None:
+        """Return the active contract for a person, if any."""
+        for contract in self._contracts.values():
+            if contract.active and person_id in contract.parties:
+                return contract
+        return None
+
+    def subject_data_categories(self, person_id: str) -> frozenset[str]:
+        """Return all permitted data categories for a person."""
+        categories: set[str] = set()
+        for contract in self._contracts.values():
+            if contract.active and person_id in contract.parties:
+                categories |= contract.scope
+        return frozenset(categories)
+
+    def revoke_contract(
+        self,
+        contract_id: str,
+        *,
+        contracts_dir: Path | None = None,
+    ) -> float:
+        """Revoke a single consent contract by ID.
+
+        Returns the wall-clock seconds the revocation took.
+        Raises KeyError if the contract_id is not registered.
+        """
+        t0 = time.monotonic()
+        contract = self._contracts.get(contract_id)
+        if contract is None:
+            raise KeyError(f"Contract {contract_id} not registered")
+
+        now_iso = datetime.now().isoformat()
+        revoked_contract = ConsentContract(
+            id=contract.id,
+            parties=contract.parties,
+            scope=contract.scope,
+            direction=contract.direction,
+            visibility_mechanism=contract.visibility_mechanism,
+            created_at=contract.created_at,
+            revoked_at=now_iso,
+            principal_class=contract.principal_class,
+            guardian=contract.guardian,
+        )
+        self._contracts[contract_id] = revoked_contract
+
+        directory = contracts_dir or self._contracts_dir
+        if directory is not None:
+            src = directory / f"{contract_id}.yaml"
+            if src.exists():
+                revoked_dir = directory / "revoked"
+                revoked_dir.mkdir(parents=True, exist_ok=True)
+                stamp = now_iso[:10]
+                dst = revoked_dir / f"{stamp}-{contract_id}.yaml"
+                n = 2
+                while dst.exists():
+                    dst = revoked_dir / f"{stamp}-{contract_id}-{n}.yaml"
+                    n += 1
+                src.rename(dst)
+                log.info("Revoked contract %s — moved YAML to %s", contract_id, dst)
+
+        elapsed = time.monotonic() - t0
+        return elapsed
+
+    def purge_subject(self, person_id: str) -> list[str]:
+        """Mark all contracts for a person as revoked. Returns revoked IDs."""
+        revoked: list[str] = []
+        for contract_id, contract in self._contracts.items():
+            if contract.active and person_id in contract.parties:
+                revoked_contract = ConsentContract(
+                    id=contract.id,
+                    parties=contract.parties,
+                    scope=contract.scope,
+                    direction=contract.direction,
+                    visibility_mechanism=contract.visibility_mechanism,
+                    created_at=contract.created_at,
+                    revoked_at=datetime.now().isoformat(),
+                    principal_class=contract.principal_class,
+                    guardian=contract.guardian,
+                )
+                self._contracts[contract_id] = revoked_contract
+                revoked.append(contract_id)
+                log.info("Revoked contract %s for %s", contract_id, person_id)
+        return revoked
+
+    def create_contract(
+        self,
+        person_id: str,
+        scope: frozenset[str],
+        *,
+        contract_id: str | None = None,
+        direction: str = "one_way",
+        visibility_mechanism: str = "on_request",
+        contracts_dir: Path | None = None,
+    ) -> ConsentContract:
+        """Create and activate a new consent contract at runtime."""
+        now = datetime.now().isoformat()
+        cid = contract_id or f"contract-{person_id}-{now[:10]}"
+
+        contract = ConsentContract(
+            id=cid,
+            parties=("operator", person_id),
+            scope=scope,
+            direction=direction,
+            visibility_mechanism=visibility_mechanism,
+            created_at=now,
+        )
+
+        directory = contracts_dir or self._contracts_dir
+        if directory is not None:
+            directory.mkdir(parents=True, exist_ok=True)
+            contract_path = directory / f"{cid}.yaml"
+            contract_data: dict[str, Any] = {
+                "id": contract.id,
+                "parties": list(contract.parties),
+                "scope": sorted(contract.scope),
+                "direction": contract.direction,
+                "visibility_mechanism": contract.visibility_mechanism,
+                "created_at": contract.created_at,
+            }
+            if contract.principal_class:
+                contract_data["principal_class"] = contract.principal_class
+            if contract.guardian:
+                contract_data["guardian"] = contract.guardian
+            contract_path.write_text(yaml.dump(contract_data, default_flow_style=False))
+            log.info("Created consent contract %s for %s at %s", cid, person_id, contract_path)
+
+        self._contracts[cid] = contract
+        return contract
+
+    @property
+    def active_contracts(self) -> list[ConsentContract]:
+        return [c for c in self._contracts.values() if c.active]
+
+
+def parse_contract(data: dict[str, Any]) -> ConsentContract:
+    """Parse a contract YAML dict into a ConsentContract."""
+    parties = data.get("parties", [])
+    if len(parties) != 2:
+        raise ValueError(f"Contract must have exactly 2 parties, got {len(parties)}")
+
+    return ConsentContract(
+        id=data["id"],
+        parties=(parties[0], parties[1]),
+        scope=frozenset(data.get("scope", [])),
+        direction=data.get("direction", "one_way"),
+        visibility_mechanism=data.get("visibility_mechanism", "on_request"),
+        created_at=data.get("created_at", ""),
+        revoked_at=data.get("revoked_at"),
+        principal_class=data.get("principal_class", ""),
+        guardian=data.get("guardian"),
+    )
+
+
+def load_contracts(contracts_dir: Path | None = None) -> ConsentRegistry:
+    """Convenience function: create and load a ConsentRegistry."""
+    registry = ConsentRegistry(_contracts_dir=contracts_dir)
+    registry.load(contracts_dir)
+    return registry
+
+
+def check_consent_state_freshness(path: Path, *, stale_threshold_s: float = 300.0) -> bool:
+    """Check if a consent state file on disk is fresh enough to trust."""
+    try:
+        mtime = path.stat().st_mtime
+        return (time.time() - mtime) < stale_threshold_s
+    except OSError:
+        return False