aetherruntime-arch 2.0.0__py3-none-any.whl

aetherruntime/monitoring/baseline.py

@@ -0,0 +1,282 @@
+"""
+AetherRuntime v2.0.0 — Monitoring: Baseline Computation
+
+This module implements Operation 2 (`update_baseline`) from
+docs/specification/02_operations.md.
+
+The `update_baseline` operation computes a statistical model of
+expected behaviour for an agent's telemetry category. It is the
+reference point for anomaly detection (Layer 2).
+
+Invariants enforced:
+    - I7: sample_count >= 10
+    - I8: parameters contains required keys for model_type
+
+Errors:
+    - E5: AgentNotFound
+    - E6: InsufficientTelemetry
+    - E7: InvalidWindowSize
+"""
+
+from __future__ import annotations
+
+import statistics
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..models import (
+    Agent,
+    Baseline,
+    BaselineModel,
+    TelemetryCategory,
+    TelemetryRecord,
+    _now_iso,
+    _random_hex,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Errors
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class AgentNotFound(Exception):
+    """E5: Agent does not exist."""
+    pass
+
+
+class InsufficientTelemetry(Exception):
+    """E6: Fewer than window_size telemetry records exist."""
+    pass
+
+
+class InvalidWindowSize(Exception):
+    """E7: window_size < 10."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Operation 2 — update_baseline
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def update_baseline(
+    agent: Agent,
+    category: TelemetryCategory,
+    model_type: BaselineModel,
+    window_size: int,
+    telemetry_records: list[TelemetryRecord],
+    existing_baseline: Optional[Baseline] = None,
+) -> Baseline:
+    """
+    Update the baseline model for an agent's telemetry category (Operation 2).
+
+    Args:
+        agent: The agent to compute a baseline for.
+        category: Telemetry category (cpu, memory, network, syscall, action).
+        model_type: Baseline model type (mean_std, zscore, moving_average, seasonal).
+        window_size: Number of recent telemetry records to use.
+        telemetry_records: All telemetry records for the agent.
+        existing_baseline: Optional existing baseline (to preserve baseline_id).
+
+    Returns:
+        A new (or updated) `Baseline` with computed parameters.
+
+    Raises:
+        AgentNotFound: If agent is None.
+        InvalidWindowSize: If window_size < 10.
+        InsufficientTelemetry: If fewer than window_size records exist.
+
+    Invariants:
+        I7: sample_count >= 10.
+        I8: parameters contains all required keys for model_type.
+
+    Example:
+        >>> agent = create_agent(public_key=...)
+        >>> records = [collect(agent, TelemetryCategory.CPU, 45.0) for _ in range(10)]
+        >>> baseline = update_baseline(agent, TelemetryCategory.CPU,
+        ...                            BaselineModel.MEAN_STD, 10, records)
+        >>> baseline.sample_count
+        10
+    """
+    # ─── P1: Agent exists ───
+    if agent is None:
+        raise AgentNotFound("agent must not be None")
+
+    # ─── P2: window_size >= 10 (I7) ───
+    if window_size < 10:
+        raise InvalidWindowSize(
+            f"window_size must be >= 10, got {window_size}"
+        )
+
+    # ─── P3: Enough telemetry records ───
+    relevant = [r for r in telemetry_records if r.category == category]
+    if len(relevant) < window_size:
+        raise InsufficientTelemetry(
+            f"need >= {window_size} records for category {category.value}, "
+            f"got {len(relevant)}"
+        )
+
+    # Use the most recent `window_size` records
+    recent = relevant[-window_size:]
+    values = [r.value for r in recent]
+
+    # ─── Compute parameters based on model_type ───
+    parameters = _compute_parameters(model_type, values)
+
+    # ─── Create or update baseline ───
+    baseline_id = existing_baseline.baseline_id if existing_baseline else _random_hex()
+
+    return Baseline(
+        baseline_id=baseline_id,
+        agent_id=agent.agent_id,
+        category=category,
+        model_type=model_type,
+        parameters=parameters,
+        computed_at=_now_iso(),
+        sample_count=len(recent),
+    )
+
+
+def _compute_parameters(model_type: BaselineModel, values: list[float]) -> dict:
+    """Compute model parameters from a list of values."""
+    if model_type == BaselineModel.MEAN_STD:
+        return {
+            "mean": statistics.mean(values),
+            "std": statistics.stdev(values) if len(values) > 1 else 0.0,
+        }
+
+    elif model_type == BaselineModel.ZSCORE:
+        mean = statistics.mean(values)
+        std = statistics.stdev(values) if len(values) > 1 else 0.0
+        return {
+            "mean": mean,
+            "std": std,
+            "z_scores": [(v - mean) / std if std > 0 else 0.0 for v in values],
+        }
+
+    elif model_type == BaselineModel.MOVING_AVERAGE:
+        return {
+            "window": len(values),
+            "values": values,
+            "moving_average": statistics.mean(values),
+        }
+
+    elif model_type == BaselineModel.SEASONAL:
+        # Simple seasonal decomposition: period = 4 (quarterly)
+        period = 4
+        return {
+            "period": period,
+            "coefficients": _seasonal_coefficients(values, period),
+            "mean": statistics.mean(values),
+        }
+
+    else:
+        raise ValueError(f"Unknown model_type: {model_type}")
+
+
+def _seasonal_coefficients(values: list[float], period: int) -> list[float]:
+    """Compute simple seasonal coefficients."""
+    if len(values) < period:
+        return [1.0] * period
+    overall_mean = statistics.mean(values)
+    if overall_mean == 0:
+        return [1.0] * period
+    coefficients = []
+    for i in range(period):
+        seasonal_values = values[i::period]
+        if seasonal_values:
+            coefficients.append(statistics.mean(seasonal_values) / overall_mean)
+        else:
+            coefficients.append(1.0)
+    return coefficients
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Batch baseline helper
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def update_all_baselines(
+    agent: Agent,
+    telemetry_records: list[TelemetryRecord],
+    model_type: BaselineModel = BaselineModel.MEAN_STD,
+    window_size: int = 10,
+) -> dict[TelemetryCategory, Baseline]:
+    """
+    Update baselines for all telemetry categories with sufficient data.
+
+    Args:
+        agent: The agent.
+        telemetry_records: All telemetry records.
+        model_type: Model type (default: mean_std).
+        window_size: Window size (default: 10).
+
+    Returns:
+        Dict mapping category → Baseline (only for categories with enough data).
+    """
+    baselines: dict[TelemetryCategory, Baseline] = {}
+    for category in TelemetryCategory:
+        relevant = [r for r in telemetry_records if r.category == category]
+        if len(relevant) >= window_size:
+            try:
+                baseline = update_baseline(
+                    agent=agent,
+                    category=category,
+                    model_type=model_type,
+                    window_size=window_size,
+                    telemetry_records=telemetry_records,
+                )
+                baselines[category] = baseline
+            except (InsufficientTelemetry, InvalidWindowSize):
+                continue
+    return baselines
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Baseline registry
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class BaselineRegistry:
+    """
+    An in-memory registry of baselines.
+
+    Used by the detection layer (Layer 2) to look up the baseline
+    for a given (agent, category) pair.
+    """
+
+    def __init__(self) -> None:
+        self._baselines: dict[tuple[str, TelemetryCategory], Baseline] = {}
+
+    def put(self, baseline: Baseline) -> None:
+        """Register a baseline."""
+        key = (baseline.agent_id, baseline.category)
+        self._baselines[key] = baseline
+
+    def get(
+        self, agent_id: str, category: TelemetryCategory
+    ) -> Optional[Baseline]:
+        """Get the baseline for an agent and category."""
+        return self._baselines.get((agent_id, category))
+
+    def get_all(self, agent_id: str) -> dict[TelemetryCategory, Baseline]:
+        """Get all baselines for an agent."""
+        return {
+            cat: bl
+            for (aid, cat), bl in self._baselines.items()
+            if aid == agent_id
+        }
+
+    def has(self, agent_id: str, category: TelemetryCategory) -> bool:
+        """Check if a baseline exists."""
+        return (agent_id, category) in self._baselines
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Module-level singleton (optional)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+default_baseline_registry = BaselineRegistry()
+"""Default baseline registry (can be replaced per-test)."""

aetherruntime/monitoring/telemetry.py

@@ -0,0 +1,235 @@
+"""
+AetherRuntime v2.0.0 — Monitoring: Telemetry Collection
+
+This module implements Operation 1 (`collect`) from
+docs/specification/02_operations.md.
+
+The `collect` operation gathers a telemetry record from a running agent.
+It is the input to the detection layer (Layer 2).
+
+Invariants enforced:
+    - I4: telemetry_id is unique (via _random_hex)
+    - I5: value is finite
+    - I6: timestamp is monotonic per agent
+
+Errors:
+    - E2: AgentNotRunning
+    - E3: InvalidValue
+    - E4: NonMonotonicTimestamp
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import (
+    Agent,
+    AgentStatus,
+    TelemetryCategory,
+    TelemetryRecord,
+    _now_iso,
+    _random_hex,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Errors
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class AgentNotRunning(Exception):
+    """E2: Agent is not in `running` state."""
+    pass
+
+
+class InvalidValue(Exception):
+    """E3: Value is not finite."""
+    pass
+
+
+class NonMonotonicTimestamp(Exception):
+    """E4: Timestamp is not monotonic per agent."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Operation 1 — collect
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def collect(
+    agent: Agent,
+    category: TelemetryCategory,
+    value: float,
+    timestamp: Optional[str] = None,
+    metadata: Optional[dict] = None,
+    previous_timestamp: Optional[str] = None,
+) -> TelemetryRecord:
+    """
+    Collect a telemetry record from a running agent (Operation 1).
+
+    Args:
+        agent: The agent to collect from. Must be in `running` state.
+        category: Telemetry category (cpu, memory, network, syscall, action).
+        value: Numeric value (unit depends on category). Must be finite.
+        timestamp: Logical time of observation (ISO 8601). Defaults to now.
+        metadata: Optional metadata (pid, tid, etc.).
+        previous_timestamp: Optional previous timestamp for monotonicity check.
+
+    Returns:
+        A new `TelemetryRecord` with a unique `telemetry_id`.
+
+    Raises:
+        AgentNotRunning: If agent.status != AgentStatus.RUNNING.
+        InvalidValue: If value is NaN or Inf.
+        NonMonotonicTimestamp: If timestamp < previous_timestamp.
+
+    Invariants:
+        I4: telemetry_id is unique (via _random_hex).
+        I5: value is finite.
+        I6: timestamp is monotonic per agent (if previous_timestamp provided).
+
+    Example:
+        >>> agent = create_agent(public_key=...)
+        >>> agent.status = AgentStatus.RUNNING
+        >>> record = collect(agent, TelemetryCategory.CPU, 45.2)
+        >>> record.value
+        45.2
+    """
+    # ─── P1: Agent must be running ───
+    if agent.status != AgentStatus.RUNNING:
+        raise AgentNotRunning(
+            f"Agent {agent.agent_id} is not running (status: {agent.status.value})"
+        )
+
+    # ─── P2: Value must be finite (I5) ───
+    if not isinstance(value, (int, float)):
+        raise InvalidValue(f"value must be int or float, got {type(value)}")
+    if value != value:  # NaN check
+        raise InvalidValue("value must not be NaN")
+    if value == float("inf") or value == float("-inf"):
+        raise InvalidValue("value must not be Inf")
+
+    # ─── P3: Timestamp must be monotonic (I6) ───
+    if timestamp is None:
+        timestamp = _now_iso()
+    if previous_timestamp is not None:
+        from datetime import datetime
+        try:
+            current_dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            previous_dt = datetime.fromisoformat(previous_timestamp.replace("Z", "+00:00"))
+        except (ValueError, AttributeError) as e:
+            raise NonMonotonicTimestamp(f"Invalid timestamp format: {e}")
+        if current_dt < previous_dt:
+            raise NonMonotonicTimestamp(
+                f"timestamp {timestamp} is before previous_timestamp {previous_timestamp}"
+            )
+
+    # ─── Q1–Q3: Create the record ───
+    return TelemetryRecord(
+        telemetry_id=_random_hex(),
+        agent_id=agent.agent_id,
+        category=category,
+        value=value,
+        timestamp=timestamp,
+        metadata=metadata or {},
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Batch collection helper
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def collect_batch(
+    agent: Agent,
+    records: list[tuple[TelemetryCategory, float]],
+) -> list[TelemetryRecord]:
+    """
+    Collect multiple telemetry records in one call.
+
+    Args:
+        agent: The agent to collect from.
+        records: List of (category, value) tuples.
+
+    Returns:
+        List of TelemetryRecord, one per input tuple.
+
+    Raises:
+        AgentNotRunning: If agent.status != AgentStatus.RUNNING.
+        InvalidValue: If any value is NaN or Inf.
+    """
+    from datetime import datetime, timezone
+
+    results: list[TelemetryRecord] = []
+    previous: Optional[str] = None
+
+    for i, (category, value) in enumerate(records):
+        # Use microsecond-precision timestamps to ensure monotonicity
+        ts = datetime.now(timezone.utc).isoformat()
+        # Small artificial delay to ensure monotonicity
+        if previous is not None:
+            ts = datetime.now(timezone.utc).isoformat()
+        record = collect(
+            agent=agent,
+            category=category,
+            value=value,
+            timestamp=ts,
+            previous_timestamp=previous,
+        )
+        results.append(record)
+        previous = ts
+
+    return results
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Telemetry log helper
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class TelemetryLog:
+    """
+    An in-memory log of telemetry records for an agent.
+
+    Used by the detection layer (Layer 2) and baseline computation.
+    """
+
+    def __init__(self) -> None:
+        self._records: dict[str, list[TelemetryRecord]] = {}
+
+    def append(self, record: TelemetryRecord) -> None:
+        """Append a record to the log (grouped by agent_id)."""
+        if record.agent_id not in self._records:
+            self._records[record.agent_id] = []
+        self._records[record.agent_id].append(record)
+
+    def get(self, agent_id: str) -> list[TelemetryRecord]:
+        """Get all records for an agent."""
+        return list(self._records.get(agent_id, []))
+
+    def get_by_category(
+        self, agent_id: str, category: TelemetryCategory
+    ) -> list[TelemetryRecord]:
+        """Get all records for an agent and category."""
+        return [
+            r for r in self._records.get(agent_id, []) if r.category == category
+        ]
+
+    def last_timestamp(self, agent_id: str) -> Optional[str]:
+        """Get the last timestamp for an agent (for monotonicity check)."""
+        records = self._records.get(agent_id, [])
+        return records[-1].timestamp if records else None
+
+    def count(self, agent_id: str) -> int:
+        """Count records for an agent."""
+        return len(self._records.get(agent_id, []))
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Module-level singleton (optional)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+default_telemetry_log = TelemetryLog()
+"""Default telemetry log (can be replaced per-test)."""

aetherruntime/recovery/__init__.py

@@ -0,0 +1,37 @@
+"""AetherRuntime — Recovery layer (Layer 5)."""
+
+from .snapshot import (
+    create_snapshot,
+    verify_snapshot,
+    SnapshotRegistry,
+    SnapshotNotFound as SnapshotSnapshotNotFound,
+    HashMismatch,
+    get_snapshot_hash,
+    compare_snapshots,
+)
+from .replay import (
+    recover,
+    RecoveryRegistry,
+    RecoveryStats,
+    AgentNotHalted,
+    SnapshotNotFound as ReplaySnapshotNotFound,
+    UnauthorizedReauthorizer,
+    VerificationFailed,
+)
+
+__all__ = [
+    "create_snapshot",
+    "verify_snapshot",
+    "SnapshotRegistry",
+    "SnapshotSnapshotNotFound",
+    "HashMismatch",
+    "get_snapshot_hash",
+    "compare_snapshots",
+    "recover",
+    "RecoveryRegistry",
+    "RecoveryStats",
+    "AgentNotHalted",
+    "ReplaySnapshotNotFound",
+    "UnauthorizedReauthorizer",
+    "VerificationFailed",
+]