mayhem-cli 0.5.1__py3-none-any.whl

mayhem/domain/checks.py

@@ -0,0 +1,173 @@
+"""Steady-state checks and evaluation records.
+
+Checks are evaluated in three phases — pre (baseline gate), during (violation
+policy), post (recovery proof). Measured values are recorded verbatim so
+summaries can quote numbers rather than adjectives.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+from mayhem.domain.common import Duration
+
+
+class ProbeType(StrEnum):
+    HTTP = "http"
+    EXEC = "exec"
+    TCP = "tcp"
+    PROCESS = "process"
+    METRIC = "metric"
+    FILE = "file"
+
+
+class HttpProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.HTTP] = ProbeType.HTTP
+    url: str
+    method: str = "GET"
+    timeout: Duration = 5.0
+    expected_status: int = 200
+
+
+class ExecProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.EXEC] = ProbeType.EXEC
+    cmd: tuple[str, ...]
+    timeout: Duration = 10.0
+    expected_exit_code: int = 0
+
+
+class TcpProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.TCP] = ProbeType.TCP
+    host: str
+    port: int = Field(ge=1, le=65535)
+    timeout: Duration = 3.0
+
+
+class ProcessProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.PROCESS] = ProbeType.PROCESS
+    name: str = ""  # process name/pattern (e.g. "nginx")
+    pid: int | None = Field(default=None, ge=1)
+    timeout: Duration = 5.0
+
+
+class MetricProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.METRIC] = ProbeType.METRIC
+    endpoint: str = ""  # metrics endpoint (e.g. "http://svc:9090/metrics")
+    query: str = ""  # metric name / label selector
+    threshold: float | None = None  # lower bound for the sampled value
+    timeout: Duration = 5.0
+
+
+class FileProbe(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    type: Literal[ProbeType.FILE] = ProbeType.FILE
+    path: str  # path to check inside the execution locus
+    contains: str | None = None  # optional content substring to require
+    timeout: Duration = 5.0
+
+
+Probe = Annotated[
+    HttpProbe | ExecProbe | TcpProbe | ProcessProbe | MetricProbe | FileProbe,
+    Field(discriminator="type"),
+]
+_probe_adapter: TypeAdapter[Probe] = TypeAdapter(Probe)
+
+
+def parse_probe(data: object) -> Probe:
+    """Parse untyped probe data into the closed probe union."""
+    return _probe_adapter.validate_python(data)
+
+
+class Expectation(BaseModel):
+    """Declarative pass criteria over measured probe results."""
+
+    model_config = ConfigDict(frozen=True)
+
+    status_eq: int | None = None
+    exit_code_eq: int | None = None
+    reachable: bool | None = None
+    p99_ms_lt: float | None = None
+    error_rate_lt: float | None = None  # fraction 0..1
+
+
+class OnPreFailure(StrEnum):
+    SKIP_RUN = "skip_run"
+    ABORT = "abort"
+
+
+class CheckLocus(StrEnum):
+    """Where a check is evaluated — distinct from the fault target's locus.
+
+    A bare (unqualified) check infers its locus from the fault target for
+    backward compatibility (ADR-M4-2); an explicit locus is honored as-is.
+    """
+
+    HOST = "host"
+    CONTAINER = "container"
+    SERVICE = "service"
+    PROCESS = "process"
+
+
+class SteadyStateCheck(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    probe: Probe
+    expect: Expectation = Field(default_factory=Expectation)
+    description: str = ""
+
+
+class CheckSpec(BaseModel):
+    """A drill check: a probe evaluated at an explicit or inferred locus (ADR-M4-2).
+
+    ``execution`` declares where the check runs (host / container / service /
+    process); when unset (None) the executor infers it from the fault target so
+    pre-0.3.0 specs behave unchanged. ``target`` names the fault target container
+    used for that inference.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    probe: Probe
+    execution: CheckLocus | None = None  # None → infer from fault target
+    expect: Expectation = Field(default_factory=Expectation)
+    target: str | None = None  # fault target container for locus inference
+
+
+class CheckPhase(StrEnum):
+    PRE = "pre"
+    DURING = "during"
+    POST = "post"
+
+
+class EvaluationResult(BaseModel):
+    """One check evaluation in one phase; stored verbatim in history."""
+
+    model_config = ConfigDict(frozen=True)
+
+    check_id: str
+    phase: CheckPhase
+    passed: bool
+    measured: dict[str, Any]  # e.g. {"status": 200, "p99_ms": 182.4}
+    evaluated_at_epoch_s: float
+    detail: str = ""
+
+    def summary(self) -> str:
+        verdict = "PASS" if self.passed else "FAIL"
+        measured = ", ".join(f"{k}={v}" for k, v in self.measured.items())
+        return f"[{self.phase.value}] {self.check_id}: {verdict} ({measured})"

mayhem/domain/common.py

@@ -0,0 +1,104 @@
+"""Shared scalar types and small pure helpers used across the domain.
+
+Duration parsing accepts the DSL grammar documented in
+``docs/reference/experiment-dsl.md``: ``30s | 5m | 1h`` (plus plain seconds).
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from typing import Annotated
+
+from pydantic import AfterValidator, BeforeValidator, PlainSerializer
+
+from mayhem.domain.errors import SchemaValidationError
+
+_DURATION_RE = re.compile(r"^(?P<value>\d+(?:\.\d+)?)(?P<unit>s|m|h)$")
+
+_BYTES_RE = re.compile(
+    r"^(?P<value>\d+(?:\.\d+)?)(?P<unit>TiB|GiB|MiB|KiB|TB|GB|MB|KB|T|G|M|K|B)?$"
+)
+
+
+def parse_duration(raw: str) -> float:
+    """Parse a duration string into seconds.
+
+    Raises:
+        SchemaValidationError: If the string does not match the grammar.
+    """
+    match = _DURATION_RE.fullmatch(raw.strip())
+    if match is None:
+        raise SchemaValidationError("duration", f"expected '<n>s|<n>m|<n|h' format, got {raw!r}")
+    value = float(match.group("value"))
+    unit = match.group("unit")
+    multiplier = {"s": 1.0, "m": 60.0, "h": 3600.0}[unit]
+    return value * multiplier
+
+
+def parse_bytes(raw: str) -> float:
+    """Parse a byte quantity string (e.g. ``256M``, ``1.5GiB``) into bytes.
+
+    Grammar accepts ``<n>`` followed by an optional unit: ``B``, ``K``/``KiB``,
+    ``M``/``MiB``, ``G``/``GiB``, ``T``/``TiB`` computed in powers of 1024, or
+    ``KB``/``MB``/``GB``/``TB`` computed in powers of 1000. A bare number is
+    plain bytes.
+
+    Raises:
+        SchemaValidationError: If the string does not match the grammar.
+    """
+    match = _BYTES_RE.fullmatch(raw.strip())
+    if match is None:
+        raise SchemaValidationError(
+            "bytes", f"expected '<n>[B|K|KB|KiB|M|MB|MiB|G|GB|GiB|T|TB|TiB]', got {raw!r}"
+        )
+    value = float(match.group("value"))
+    unit = match.group("unit") or "B"
+    base = 1024.0 if unit.endswith("iB") or len(unit) == 1 else 1000.0
+    power = {"B": 0, "K": 1, "M": 2, "G": 3, "T": 4}[unit[0]]
+    return value * base**power
+
+
+def _coerce_duration(v: object) -> object:
+    return parse_duration(v) if isinstance(v, str) else v
+
+
+def _check_non_negative(v: float | str) -> float:
+    seconds = parse_duration(v) if isinstance(v, str) else float(v)
+    if seconds < 0:
+        raise SchemaValidationError("duration", f"must be >= 0, got {v}")
+    return seconds
+
+
+def _serialize_duration(v: float | str) -> str:
+    seconds = parse_duration(v) if isinstance(v, str) else float(v)
+    return f"{seconds:g}s"
+
+
+Duration = Annotated[
+    float | str,
+    BeforeValidator(_coerce_duration),
+    AfterValidator(_check_non_negative),
+    PlainSerializer(_serialize_duration, return_type=str),
+]
+"""Seconds; accepts DSL duration strings (``"30s"``/``"5m"``/``"1h"``) or a
+plain ``float`` of seconds, and emits a seconds string on serialization.
+
+The declared type is ``float | str`` because an unpassed class default is
+returned by Pydantic v2 *without* running the validator (see
+``tests/unit/test_drill_spec.py`` asserting ``DrillConfig().timeout == "30m"``),
+so a string default must be type-valid. Explicitly supplied values are coerced
+to ``float`` seconds at validation time.
+"""
+
+
+def utc_now() -> datetime:
+    """Timezone-aware UTC now (DTZ discipline: never naive datetimes)."""
+    return datetime.now(UTC)
+
+
+def iso_utc(dt: datetime) -> str:
+    """Render a datetime as ISO-8601 UTC text, as persisted in storage."""
+    if dt.tzinfo is None:
+        raise SchemaValidationError("timestamp", "naive datetime refused; require tz-aware")
+    return dt.astimezone(UTC).isoformat()

mayhem/domain/coverage.py

@@ -0,0 +1,106 @@
+"""Coverage accounting — ADR-M5-3 (coverage is the objective).
+
+A ``CoverageCell`` is a point in the experiment landscape:
+(``target``, ``fault_kind``, ``execution_context``, ``parameter_band``).
+
+A recorded ``Outcome`` marks the cell for its run as *seen*; Maniac then
+optimizes toward covering new (``UNKNOWN``) cells rather than re-running
+already-covered ones. A re-run of the same cell never double-counts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CoverageCell:
+    """One point in the (target, fault-kind, context, parameter-band) landscape."""
+
+    target: str
+    fault_kind: str
+    execution_context: str
+    parameter_band: str
+
+    @property
+    def key(self) -> str:
+        """Canonical, collision-resistant key for this cell."""
+        return _cell_key(self.target, self.fault_kind, self.execution_context, self.parameter_band)
+
+    def to_tuple(self) -> tuple[str, str, str, str]:
+        return (self.target, self.fault_kind, self.execution_context, self.parameter_band)
+
+    @classmethod
+    def from_tuple(cls, row: tuple[str, str, str, str]) -> CoverageCell:
+        return cls(*row)
+
+
+def _cell_key(
+    target: str,
+    fault_kind: str,
+    execution_context: str,
+    parameter_band: str,
+) -> str:
+    """Deterministic key; ``"\x1f"`` (unit separator) is not valid in the parts."""
+    if any("\x1f" in p for p in (target, fault_kind, execution_context, parameter_band)):
+        raise ValueError("coverage cell parts must not contain the unit separator char")
+    return "\x1f".join((target, fault_kind, execution_context, parameter_band))
+
+
+def cell_key(
+    target: str,
+    fault_kind: str,
+    execution_context: str,
+    parameter_band: str,
+) -> str:
+    """Module-level helper mirroring ``CoverageCell.key``."""
+    return _cell_key(target, fault_kind, execution_context, parameter_band)
+
+
+@dataclass(frozen=True)
+class CoverageRecord:
+    """A persisted *seen* cell plus metadata about its originating run."""
+
+    cell: CoverageCell
+    run_id: str
+    outcome_marks_seen: bool = True
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def key(self) -> str:
+        return self.cell.key
+
+
+@dataclass(frozen=True)
+class CoverageSummary:
+    """Aggregate view of covered vs unknown cells over a landscape."""
+
+    covered_keys: frozenset[str]
+    total_cells: int
+
+    @property
+    def covered_count(self) -> int:
+        return len(self.covered_keys)
+
+    @property
+    def unknown_count(self) -> int:
+        return self.total_cells - self.covered_count
+
+    @property
+    def fraction(self) -> float:
+        """Fraction of the landscape covered, in [0.0, 1.0]."""
+        if self.total_cells == 0:
+            return 0.0
+        return self.covered_count / self.total_cells
+
+    def is_covered(self, cell: CoverageCell) -> bool:
+        return cell.key in self.covered_keys
+
+    def unknown_cells(self, landscape: tuple[CoverageCell, ...]) -> tuple[CoverageCell, ...]:
+        """Cells in ``landscape`` not yet covered, in landscape order."""
+        return tuple(c for c in landscape if c.key not in self.covered_keys)
+
+    def cell_was_seen(self, value: CoverageCell) -> bool:
+        """Alias of ``is_covered`` for call sites reading 'seen' language."""
+        return self.is_covered(value)

mayhem/domain/decisions.py

@@ -0,0 +1,57 @@
+"""Governing-decision registry — ADR decision IDs + decided-on timestamps.
+
+Every outcome record carries the decision refs that produced it, so a replay
+can attribute a verdict, its criteria, and its observations to the approved
+decisions that defined them (ADR-M4-1/4-3/4-4/4-5). The ID is the ADR's own
+name and the timestamp is the date it was approved — captured here once and
+persisted on the run row by the executor.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DecisionRef(BaseModel):
+    """A single governing decision: ADR id + approval timestamp."""
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str
+    decided_on: str  # ISO date the decision was approved
+    title: str = ""
+
+    def summary(self) -> str:
+        """One-line human description: ``ADR-M4-3 2026-09-05 (title)``."""
+        return f"{self.decision_id} {self.decided_on} ({self.title})"
+
+
+DECISION_M4_1_ADDITIVE_DSL = DecisionRef(
+    decision_id="ADR-M4-1",
+    decided_on="2026-09-02",
+    title="Additive, non-breaking DSL sections + typed Duration",
+)
+
+DECISION_M4_3_SUCCESS_CRITERIA = DecisionRef(
+    decision_id="ADR-M4-3",
+    decided_on="2026-09-05",
+    title="Machine-evaluable success criteria + run verdict",
+)
+
+DECISION_M4_4_OBSERVABILITY = DecisionRef(
+    decision_id="ADR-M4-4",
+    decided_on="2026-09-05",
+    title="Declarative observability/metrics sources",
+)
+
+DECISION_M4_5_SCHEMA_FREEZE = DecisionRef(
+    decision_id="ADR-M4-5",
+    decided_on="2026-09-02",
+    title="Schema freeze + versioned migrations with up/down",
+)
+
+DECISION_M5_1_MANIAC = DecisionRef(
+    decision_id="ADR-M5-1",
+    decided_on="2026-09-06",
+    title="Maniac mode: random fault injection dialed by config",
+)

mayhem/domain/errors.py

@@ -0,0 +1,87 @@
+"""Structured domain failures.
+
+Errors are part of the API (ADR-0002 discipline): every refusal or invariant
+violation raises a typed error that is safe to render, log, and persist.
+"""
+
+from __future__ import annotations
+
+
+class DomainError(Exception):
+    """Base class for all domain-layer failures."""
+
+
+class InvalidTransitionError(DomainError):
+    """A state machine rejected a transition.
+
+    Attributes:
+        entity: Kind of stateful entity, e.g. ``"fault_lease"``.
+        entity_id: Identifier of the offending instance.
+        current: Current state value.
+        requested: State value that was requested.
+    """
+
+    def __init__(self, entity: str, entity_id: str, current: str, requested: str) -> None:
+        self.entity = entity
+        self.entity_id = entity_id
+        self.current = current
+        self.requested = requested
+        super().__init__(
+            f"{entity} '{entity_id}' cannot transition from '{current}' to '{requested}'"
+        )
+
+
+class InvariantViolationError(DomainError):
+    """A documented domain invariant was violated.
+
+    Attributes:
+        rule: Stable identifier of the violated invariant, e.g. ``undo_required_before_active``.
+        message: Human-readable explanation with enough context to debug.
+    """
+
+    def __init__(self, rule: str, message: str) -> None:
+        self.rule = rule
+        super().__init__(f"[{rule}] {message}")
+
+
+class TargetResolutionError(DomainError):
+    """A declarative target selector matched nothing resolvable."""
+
+    def __init__(self, selector: str, reason: str) -> None:
+        self.selector = selector
+        super().__init__(f"target selector '{selector}' unresolved: {reason}")
+
+
+class SchemaValidationError(DomainError):
+    """Fault params or experiment spec failed schema validation."""
+
+    def __init__(self, subject: str, reason: str) -> None:
+        self.subject = subject
+        super().__init__(f"{subject}: {reason}")
+
+
+class TargetDriftError(DomainError):
+    """The planned ``RuntimeIdentity`` no longer matches the live one.
+
+    Declared in M1 (ADR-M1-3); *raised* in M2 when live re-validation
+    detects that a container was recreated mid-run under the same authored
+    name. Distinct from capability failures and ownership contention — a
+    drifted target is mismatched, not failed.
+    """
+
+    def __init__(
+        self,
+        run_id: str,
+        step_id: str,
+        planned: str,
+        live: str,
+    ) -> None:
+        self.run_id = run_id
+        self.step_id = step_id
+        self.planned = planned
+        self.live = live
+        super().__init__(
+            f"target drift on step '{step_id}' (run '{run_id}'): "
+            f"planned identity '{planned}' no longer matches live "
+            f"identity '{live}'"
+        )

mayhem/domain/events.py

@@ -0,0 +1,61 @@
+"""Typed event union flowing through the observation hub.
+
+Events are append-only facts. Agents emit them over their channel; the
+controller persists them (SQLite) and mirrors them into the run journal.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+from mayhem.domain.common import utc_now
+
+
+class EventKind(StrEnum):
+    RUN_STARTED = "run.started"
+    RUN_COMPLETED = "run.completed"
+    RUN_FAILED = "run.failed"
+    RUN_ABORT_REQUESTED = "run.abort_requested"
+    RUN_ABORTED = "run.aborted"
+    STEP_STARTED = "step.started"
+    STEP_FINISHED = "step.finished"
+    STEP_SKIPPED = "step.skipped"
+    FAULT_INJECTED = "fault.injected"
+    FAULT_OBSERVED = "fault.observed"
+    FAULT_RECOVERED = "fault.recovered"
+    FAULT_FAILED = "fault.failed"
+    TOOL_EXECUTED = "tool.executed"
+    CHECK_EVALUATED = "check.evaluated"
+    CRITERIA_EVALUATED = "criteria.evaluated"
+    OBSERVABILITY_COLLECTED = "observability.collected"
+    OBSERVABILITY_SOURCE_FAILED = "observability.source_failed"
+    LEASE_STATE_CHANGED = "lease.state_changed"
+    AGENT_STATE_CHANGED = "agent.state_changed"
+    DRIFT_REPORTED = "drift.reported"
+    SAFETY_REFUSED = "safety.refused"
+    MANIAC_DECISION = "maniac.decision"
+
+
+class Event(BaseModel):
+    """Base envelope; concrete events add typed payloads via ``detail``."""
+
+    model_config = ConfigDict(frozen=True)
+
+    kind: EventKind
+    run_id: str | None = None
+    detail: dict[str, Any] = Field(default_factory=dict)
+    created_at_epoch_s: float = Field(default_factory=lambda: utc_now().timestamp())
+
+    def render_line(self) -> str:
+        """Single-line journal rendering; structured enough to grep."""
+        parts = [f"{self.kind.value}"]
+        if self.run_id:
+            parts.append(f"run={self.run_id}")
+        parts.extend(f"{k}={v}" for k, v in sorted(self.detail.items()))
+        return " ".join(parts)
+
+
+EventStream: TypeAdapter[list[Event]] = TypeAdapter(list[Event])