mayhem-cli 0.5.1__py3-none-any.whl

mayhem/domain/candidates.py

@@ -0,0 +1,101 @@
+"""ExperimentCandidate — ADR-M5-2 (M5 Phase 5.3).
+
+A candidate is a *proposal* for an experiment: what to poke (target, fault
+kinds, params), where (execution context), why (expected effect), and how
+risky (risk band). It is not executable until it has passed the three gates:
+
+    Safety → Feasibility → Resource-conflict
+
+A candidate that fails a gate carries the failing gate and a reason; it is
+rejected, never executed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from mayhem.domain.risks import RiskLevel
+
+
+class CandidateGate(StrEnum):
+    """The three gates every executable candidate must pass (ADR-M5-2)."""
+
+    SAFETY = "safety"  # ADR-M5 / controller safety checks
+    FEASIBILITY = "feasibility"  # M3 runtime-capability verdicts
+    RESOURCE_CONFLICT = "resource_conflict"  # M2 resource-conflict checks
+
+
+class CandidateStatus(StrEnum):
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True)
+class ExperimentCandidate:
+    """A proposal to run one experiment against one target cell."""
+
+    target: str
+    fault_kinds: tuple[str, ...]
+    params: dict[str, Any] = field(default_factory=dict)
+    execution_context: str = "container"
+    expected_effect: str = ""
+    risk_band: RiskLevel = RiskLevel.LOW
+    seed_hint: int = 0  # ties a candidate to a deterministic generator seed
+
+    @property
+    def id(self) -> str:
+        """Stable id derived from the candidate's defining fields + seed."""
+        digest = hashlib.sha256(
+            f"{self.target}\x1f"
+            f"{','.join(self.fault_kinds)}\x1f"
+            f"{self.execution_context}\x1f"
+            f"{self.risk_band.value}\x1f"
+            f"{self.seed_hint}".encode()
+        ).hexdigest()[:16]
+        return f"cand-{digest}"
+
+    @property
+    def primary_fault(self) -> str:
+        return self.fault_kinds[0] if self.fault_kinds else ""
+
+
+@dataclass(frozen=True)
+class CandidateDecision:
+    """Outcome of routing a candidate through the three gates."""
+
+    candidate: ExperimentCandidate
+    status: CandidateStatus
+    gate: CandidateGate | None = None  # which gate rejected it
+    reason: str = ""
+
+    @property
+    def accepted(self) -> bool:
+        return self.status is CandidateStatus.ACCEPTED
+
+    @property
+    def rejected(self) -> bool:
+        return self.status is CandidateStatus.REJECTED
+
+    @property
+    def summary(self) -> str:
+        if self.accepted:
+            fault = self.candidate.primary_fault
+            return f"ACCEPT {self.candidate.id} ({self.candidate.target}/{fault})"
+        gate = self.gate.value if self.gate is not None else "unknown"
+        return f"REJECT[{gate}] {self.candidate.id}: {self.reason}"
+
+
+def accept(candidate: ExperimentCandidate) -> CandidateDecision:
+    return CandidateDecision(candidate=candidate, status=CandidateStatus.ACCEPTED)
+
+
+def reject(candidate: ExperimentCandidate, gate: CandidateGate, reason: str) -> CandidateDecision:
+    return CandidateDecision(
+        candidate=candidate,
+        status=CandidateStatus.REJECTED,
+        gate=gate,
+        reason=reason,
+    )

mayhem/domain/capabilities.py

@@ -0,0 +1,86 @@
+"""Capability and tool-manifest types (ADR-0004).
+
+Agents declare *capabilities*; tools are wrapped behind manifests so faults ask
+for outcomes, not binaries. Fallback groups let the executor pick any tool that
+can deliver a capability on the current host.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+Identifier = Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9_.-]{1,63}$")]
+"""Lowercase dotted identifier, e.g. ``net.latency`` or ``tc-netem``."""
+
+
+class PrivilegeMode(StrEnum):
+    """How privileged operations are obtained on a host (ADR-0003)."""
+
+    ROOT_VIA_SYSTEMD = "root_via_systemd"
+    SUDO_PINNED = "sudo_pinned"
+    UNPRIVILEGED = "unprivileged"
+
+
+class Capability(StrEnum):
+    """Named host abilities agents advertise during handshake."""
+
+    NET_ADMIN = "net_admin"
+    SYS_ADMIN = "sys_admin"
+    CGROUP_CONTROL = "cgroup_control"
+    PROCESS_CONTROL = "process_control"
+    FS_CONTROL = "fs_control"
+    DOCKER_ENGINE = "docker_engine"
+    PODMAN_ENGINE = "podman_engine"
+    KUBERNETES_ENGINE = "kubernetes_engine"
+
+
+class ToolManifest(BaseModel):
+    """Declarative wrapper around one native or external tool.
+
+    In-tree YAML manifests deserialize into this model; adapters implement the
+    behavior. ``fallback_group`` ties interchangeable tools together (ADR-0010).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: Identifier
+    display_name: str
+    binary: str
+    capability_group: Identifier  # e.g. "net.emulation", "load.http"
+    provides_capabilities: frozenset[Capability] = Field(default_factory=frozenset)
+    requires_privilege_mode: PrivilegeMode | None = None
+    version_flag: tuple[str, ...] = ("--version",)
+    default_timeout_s: float = 30.0
+    output_limit_bytes: int = 1_048_576  # truncation is always explicit
+
+
+class ToolAvailability(BaseModel):
+    """Result of probing one manifest on one host."""
+
+    model_config = ConfigDict(frozen=True)
+
+    manifest_id: Identifier
+    available: bool
+    version: str | None = None
+    reason_if_unavailable: str | None = None
+
+
+class CapabilityReport(BaseModel):
+    """What an agent can actually do right now (handshake payload)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    agent_id: str
+    host: str
+    privilege_mode: PrivilegeMode
+    capabilities: frozenset[Capability] = Field(default_factory=frozenset)
+    tools: tuple[ToolAvailability, ...] = ()
+
+    def has_capability(self, cap: Capability) -> bool:
+        return cap in self.capabilities
+
+    def missing(self, needed: frozenset[Capability]) -> frozenset[Capability]:
+        return needed - self.capabilities