Add propagation engine, log templates, and updated models

- server/propagation.py: queueing theory cascade engine with circuit breakers,
Little's Law utilization, retry amplification, and multi-hop propagation
- server/logs.py: framework-specific log templates for all 8 failure types
(Spring Boot, Node.js, FastAPI, K8s, HikariCP, Redis, gRPC patterns)
- models.py: cleaned up Pydantic models for API contract
- pyproject.toml: updated dependencies
- uv.lock: locked dependency versions
- README.md: initial project readme

README.md

@@ -0,0 +1,7 @@
+# SevZero — SRE Incident Response Environment
+
+An autonomous on-call SRE managing a microservice cluster undergoing cascading failures.
+
+Built with [OpenEnv](https://github.com/meta-pytorch/OpenEnv) for the OpenEnv AI Hackathon 2026.
+
+> Full documentation coming soon.

models.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional, Union
 
-from pydantic import Field
+from pydantic import BaseModel, Field
 
 from openenv.core.env_server import Action, Observation, State
 
@@ -20,22 +20,6 @@ from openenv.core.env_server import Action, Observation, State
 # ---------------------------------------------------------------------------
 
 
-class CircuitBreakerInfo(dict):
-    """Maps dependency name -> breaker state ('CLOSED' | 'OPEN' | 'HALF_OPEN')."""
-
-
-class ServiceInfo(object):
-    """Per-service observable state — declared as plain dict in observation for
-    JSON-serialisability; structured via ServiceInfoModel for validation."""
-
-
-class ServiceInfoModel:
-    """Pydantic model for a single service's metrics (used internally)."""
-
-
-from pydantic import BaseModel
-
-
 class ServiceInfoModel(BaseModel):
     """
     All observable per-service metrics, ordered by SRE triage priority:

pyproject.toml

@@ -25,8 +25,8 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["server"]
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
     "pytest>=7.0.0",
     "httpx>=0.24.0",
 ]

server/logs.py

@@ -0,0 +1,268 @@
+"""
+server/logs.py — Framework-specific log message templates per failure type.
+
+Each failure type has 5-10 realistic log templates drawn from real frameworks:
+Spring Boot, Node.js, FastAPI, Kubernetes, HikariCP, Redis, gRPC.
+
+Templates use placeholders {service}, {dependency}, {value} etc. that are
+filled at runtime with actual service/metric values.
+
+Sources: Docs/DataResearch.md Answer 4 + Answer 11.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, List, Optional
+
+from server.failures import FailureType
+
+
+# ---------------------------------------------------------------------------
+# Log templates per failure type
+# ---------------------------------------------------------------------------
+
+_TEMPLATES: Dict[FailureType, List[str]] = {
+    FailureType.CRASH: [
+        "ERROR {service} OOMKilled: container exceeded memory limit ({memory_limit}Mi). Exit code 137. Pod restarting (backoff: {backoff}s)",
+        "FATAL {service} Process exited with signal 9 (SIGKILL). Out of memory. Restart count: {restart_count}",
+        "ERROR {service} CrashLoopBackOff: back-off restarting failed container. Last exit: OOMKilled",
+        "CRIT {service} JVM heap exhausted: java.lang.OutOfMemoryError: Java heap space. Heap: {heap_used}Mi/{heap_max}Mi",
+        "ERROR {service} Panic: runtime error: out of memory. goroutine stack overflow at allocateHeap()",
+        "FATAL {service} Node process crashed: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory",
+    ],
+
+    FailureType.BAD_DEPLOY: [
+        "ERROR {service} {version} NullPointerException: Cannot invoke \"{method}\" on null reference at {class}.process({class}.java:{line})",
+        "ERROR {service} {version} TypeError: Cannot read properties of undefined (reading '{property}'). Stack: at {handler} ({file}:{line})",
+        "ERROR {service} {version} Traceback (most recent call last):\\n  File \"{file}\", line {line}\\n    {code_line}\\nAttributeError: '{class}' object has no attribute '{attribute}'",
+        "ERROR {service} {version} panic: interface conversion: interface {} is nil, not *{type}. goroutine {goroutine_id} [running]",
+        "ERROR {service} {version} Unhandled rejection: ValidationError: \"{field}\" is required. Schema version mismatch between {version} and data format.",
+        "WARN  {service} {version} Health check failing: /health returned 500. Error rate climbing: {error_rate}%",
+    ],
+
+    FailureType.CONFIG_STARTUP: [
+        "FATAL {service} password authentication failed for user \"{db_user}\" on {dependency}:{port}. Connection refused.",
+        "ERROR {service} Could not resolve placeholder '{config_key}' in value \"${{{config_key}}}\"",
+        "FATAL {service} Configuration error: required key [{config_key}] not found in application.yml",
+        "ERROR {service} Failed to bind to port {port}: EADDRINUSE. Another process is using this port.",
+        "FATAL {service} SSL/TLS certificate error: certificate has expired. CN={dependency}. Valid until: {expiry}",
+        "ERROR {service} Cannot connect to {dependency}: Connection refused. Retried {retry_count} times, giving up.",
+    ],
+
+    FailureType.CONFIG_RUNTIME: [
+        "ERROR {service} Request to https://{config_value}/charge failed: ECONNREFUSED. Feature \"{feature_flag}\" enabled but endpoint misconfigured.",
+        "WARN  {service} Fallback triggered for {dependency}: timeout after {timeout_ms}ms. Config key '{config_key}' may be incorrect.",
+        "ERROR {service} Invalid JSON response from {dependency}: Unexpected token '<' at position 0. Endpoint returning HTML instead of API response.",
+        "ERROR {service} Feature flag '{feature_flag}' enabled new code path but dependency '{dependency}' not configured. Returning 500 for {error_rate}% of /api/v2 requests.",
+        "WARN  {service} Rate limit config mismatch: max_rps={config_value} but actual traffic is {throughput}rps. Dropping {error_rate}% of requests.",
+    ],
+
+    FailureType.CASCADING_LATENCY: [
+        "WARN  {service} Downstream {dependency} timeout after {timeout_ms}ms. Circuit breaker OPEN for {cooldown}s. {queued} requests queued.",
+        "WARN  {service} Thread pool exhaustion: {active}/{pool_size} threads active. Queue depth: {queue_depth}. Avg wait: {wait_ms}ms.",
+        "ERROR {service} gRPC deadline exceeded: remaining_ms={remaining_ms}. Upstream deadline propagated through {hop_count} hops.",
+        "WARN  {service} Connection pool to {dependency}: active={active}/{pool_size}, pending={pending}. Avg checkout time: {checkout_ms}ms (threshold: {threshold_ms}ms).",
+        "ERROR {service} Request timeout: {dependency} did not respond within {timeout_ms}ms. Retry {retry_count}/{retry_max}.",
+        "WARN  {service} p99 latency spike: {p99_ms}ms (baseline: {baseline_ms}ms). {dependency} response time degrading.",
+    ],
+
+    FailureType.RESOURCE_LEAK: [
+        "WARN  {service} Memory usage {memory_pct}% ({memory_used}Mi/{memory_limit}Mi). GC overhead {gc_pct}%. Last full GC: {gc_pause}s pause. Allocation failure imminent.",
+        "WARN  {service} File descriptor leak detected: open_fds={open_fds} (limit: {fd_limit}). Growing at {fd_rate}/min.",
+        "WARN  {service} Goroutine leak: count={goroutine_count} (baseline: {baseline}). Growing linearly. Stack trace: {leak_source}",
+        "ERROR {service} GC overhead limit exceeded: spending {gc_pct}% of time in GC. Heap: {memory_used}Mi/{memory_limit}Mi.",
+        "WARN  {service} Connection leak to {dependency}: {active} connections checked out but not returned. Pool: {active}/{pool_size}.",
+    ],
+
+    FailureType.DB_DEGRADATION: [
+        "ERROR {service} HikariPool-1 connection not available, request timed out after {timeout_ms}ms. Active: {active}/{pool_size}, Waiting: {waiting}.",
+        "WARN  {service} Slow query detected: SELECT * FROM {table} WHERE ... took {query_ms}ms (threshold: {threshold_ms}ms). Lock contention on {table}.",
+        "ERROR {service} Connection pool exhausted for {dependency}. Active: {active}/{pool_size}. Oldest connection age: {age_ms}ms.",
+        "WARN  {service} Database replication lag: {lag_ms}ms on {dependency}. Read-after-write consistency violated.",
+        "ERROR {service} Deadlock detected on {dependency}: Transaction {tx_id} waiting for lock held by {blocking_tx}. Auto-rolling back.",
+        "WARN  {service} {dependency} CPU={db_cpu}% but app CPU={app_cpu}% (paradoxically low). Threads blocked on I/O wait.",
+    ],
+
+    FailureType.CACHE_FAILURE: [
+        "WARN  {service} CLUSTERDOWN: {dependency} cluster is down. Hit rate dropped from {baseline_hit_rate}% to 0%. Backend QPS spiked {spike_factor}x.",
+        "ERROR {service} Redis connection lost: {dependency} ECONNRESET. Failover in progress. Cache miss rate: 100%.",
+        "WARN  {service} Cache stampede detected: {concurrent_misses} concurrent cache misses for key pattern '{key_pattern}'. Backend overloaded.",
+        "ERROR {service} {dependency} READONLY: Redis replica cannot accept writes. Cluster rebalancing.",
+        "WARN  {service} Cache eviction storm: {evicted} keys evicted in last {interval}s. Memory pressure on {dependency}.",
+    ],
+
+    FailureType.NETWORK_ERROR: [
+        "ERROR {service} DNS resolution failed for {dependency}.{region}.internal: NXDOMAIN. 0/{endpoint_count} endpoints reachable.",
+        "ERROR {service} TCP connection to {dependency}:{port} failed: ETIMEDOUT after {timeout_ms}ms. Network partition suspected.",
+        "ERROR {service} TLS handshake failed with {dependency}: certificate verify failed (depth 0). CN mismatch or expired cert.",
+        "CRIT  {service} All endpoints for {dependency} unreachable in region {region}. Last successful connection: {last_success} ago.",
+        "ERROR {service} gRPC transport error: UNAVAILABLE: {dependency} DNS resolution failed for \"{dependency}.svc.cluster.local\"",
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Placeholder value generators
+# ---------------------------------------------------------------------------
+
+
+def _random_class_name(rng: random.Random) -> str:
+    prefixes = ["Payment", "Order", "Auth", "Inventory", "Cart", "Billing", "Shipping"]
+    suffixes = ["Service", "Handler", "Controller", "Processor", "Manager"]
+    return rng.choice(prefixes) + rng.choice(suffixes)
+
+
+def _random_method(rng: random.Random) -> str:
+    return rng.choice(["process", "handle", "execute", "validate", "transform", "serialize", "getId", "getStatus"])
+
+
+def _random_property(rng: random.Random) -> str:
+    return rng.choice(["id", "status", "amount", "userId", "orderId", "timestamp", "payload", "response"])
+
+
+def _fill_placeholders(
+    template: str,
+    service_id: str,
+    rng: random.Random,
+    dependency: str = "unknown",
+    error_rate: float = 0.0,
+    memory_pct: float = 50.0,
+    p99_ms: float = 100.0,
+    pool_pct: float = 10.0,
+    version: str = "v1.0.0",
+    config_key: str = "db_host",
+    config_value: str = "wrong-endpoint.internal",
+    region: str = "us-east-1",
+    throughput: float = 100.0,
+) -> str:
+    """Fill placeholders in a log template with realistic values."""
+    replacements = {
+        "service": service_id,
+        "dependency": dependency,
+        "version": version,
+        "error_rate": f"{error_rate * 100:.0f}",
+        "memory_pct": f"{memory_pct:.0f}",
+        "memory_used": f"{int(memory_pct * 20.48):.0f}",
+        "memory_limit": "2048",
+        "heap_used": f"{int(memory_pct * 10.24):.0f}",
+        "heap_max": "1024",
+        "p99_ms": f"{p99_ms:.0f}",
+        "baseline_ms": f"{rng.randint(20, 80)}",
+        "timeout_ms": f"{rng.choice([3000, 5000, 10000, 30000])}",
+        "cooldown": f"{rng.randint(15, 60)}",
+        "queued": f"{rng.randint(50, 500)}",
+        "queue_depth": f"{rng.randint(100, 1000)}",
+        "wait_ms": f"{rng.randint(500, 5000)}",
+        "active": f"{rng.randint(15, 25)}",
+        "pool_size": "20",
+        "pending": f"{rng.randint(50, 200)}",
+        "checkout_ms": f"{rng.randint(1000, 10000)}",
+        "threshold_ms": "1000",
+        "retry_count": f"{rng.randint(1, 5)}",
+        "retry_max": "3",
+        "backoff": f"{rng.choice([10, 15, 30, 60])}",
+        "restart_count": f"{rng.randint(3, 15)}",
+        "port": f"{rng.choice([5432, 6379, 8080, 9090, 3000])}",
+        "db_user": rng.choice(["app_user", "service_account", "auth_user", "readonly"]),
+        "config_key": config_key,
+        "config_value": config_value,
+        "feature_flag": rng.choice(["new_checkout_flow", "v2_api", "experimental_search", "dynamic_pricing"]),
+        "region": region,
+        "endpoint_count": f"{rng.randint(2, 5)}",
+        "class": _random_class_name(rng),
+        "method": _random_method(rng),
+        "property": _random_property(rng),
+        "attribute": _random_property(rng),
+        "type": _random_class_name(rng),
+        "handler": rng.choice(["processRequest", "handleEvent", "onMessage"]),
+        "file": rng.choice(["app.py", "handler.js", "service.go", "controller.java"]),
+        "line": f"{rng.randint(42, 350)}",
+        "code_line": rng.choice(["result = response.data['items']", "return self.client.process(payload)"]),
+        "field": rng.choice(["amount", "currency", "userId", "orderId"]),
+        "goroutine_id": f"{rng.randint(100, 999)}",
+        "table": rng.choice(["orders", "payments", "users", "inventory", "sessions"]),
+        "query_ms": f"{rng.randint(5000, 30000)}",
+        "tx_id": f"tx-{rng.randint(1000, 9999)}",
+        "blocking_tx": f"tx-{rng.randint(1000, 9999)}",
+        "lag_ms": f"{rng.randint(1000, 10000)}",
+        "age_ms": f"{rng.randint(30000, 120000)}",
+        "db_cpu": f"{rng.randint(5, 25)}",
+        "app_cpu": f"{rng.randint(2, 15)}",
+        "waiting": f"{rng.randint(50, 300)}",
+        "baseline_hit_rate": f"{rng.uniform(95.0, 99.5):.1f}",
+        "spike_factor": f"{rng.randint(10, 50)}",
+        "concurrent_misses": f"{rng.randint(100, 1000)}",
+        "key_pattern": rng.choice(["user:*", "product:*:price", "session:*", "inventory:*"]),
+        "evicted": f"{rng.randint(10000, 100000)}",
+        "interval": f"{rng.randint(10, 60)}",
+        "gc_pct": f"{rng.randint(30, 70)}",
+        "gc_pause": f"{rng.uniform(0.5, 3.0):.1f}",
+        "open_fds": f"{rng.randint(800, 1024)}",
+        "fd_limit": "1024",
+        "fd_rate": f"{rng.randint(5, 20)}",
+        "goroutine_count": f"{rng.randint(5000, 50000)}",
+        "baseline": f"{rng.randint(50, 200)}",
+        "leak_source": rng.choice(["http.ListenAndServe", "grpc.NewServer", "sql.Open"]),
+        "hop_count": f"{rng.randint(2, 5)}",
+        "remaining_ms": f"{rng.randint(-500, 10)}",
+        "last_success": rng.choice(["45s", "2m30s", "5m12s"]),
+        "throughput": f"{throughput:.0f}",
+    }
+
+    result = template
+    for key, value in replacements.items():
+        result = result.replace("{" + key + "}", str(value))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def generate_log_message(
+    failure_type: FailureType,
+    service_id: str,
+    rng: random.Random,
+    dependency: str = "unknown",
+    error_rate: float = 0.0,
+    memory_pct: float = 50.0,
+    p99_ms: float = 100.0,
+    pool_pct: float = 10.0,
+    version: str = "v1.0.0",
+    config_key: str = "db_host",
+    config_value: str = "wrong-endpoint.internal",
+    region: str = "us-east-1",
+    throughput: float = 100.0,
+) -> str:
+    """Generate a realistic log message for the given failure type and service."""
+    templates = _TEMPLATES.get(failure_type, [])
+    if not templates:
+        return f"ERROR {service_id} Unknown failure condition detected."
+
+    template = rng.choice(templates)
+    return _fill_placeholders(
+        template, service_id, rng,
+        dependency=dependency,
+        error_rate=error_rate,
+        memory_pct=memory_pct,
+        p99_ms=p99_ms,
+        pool_pct=pool_pct,
+        version=version,
+        config_key=config_key,
+        config_value=config_value,
+        region=region,
+        throughput=throughput,
+    )
+
+
+def generate_healthy_log(service_id: str, rng: random.Random) -> str:
+    """Generate a log message for a healthy service being inspected."""
+    templates = [
+        f"INFO  {service_id} Health check passed. Status: UP. Response time: {rng.randint(2, 15)}ms.",
+        f"INFO  {service_id} All endpoints healthy. Error rate: 0.0%. p99: {rng.randint(10, 50)}ms.",
+        f"DEBUG {service_id} Metrics nominal. CPU: {rng.randint(5, 25)}%, Memory: {rng.randint(20, 45)}%, Connections: {rng.randint(2, 10)}/20.",
+        f"INFO  {service_id} No anomalies detected in last 60s. request_count={rng.randint(500, 2000)}, error_count=0.",
+    ]
+    return rng.choice(templates)

server/propagation.py

@@ -0,0 +1,323 @@
+"""
+server/propagation.py — Queueing-theory cascade engine.
+
+Computes how failures propagate through the service dependency graph using:
+- Little's Law: L = λ × S for thread pool saturation (ρ = L/T)
+- Retry amplification: E[attempts] = (1 - p^(R+1)) / (1 - p)
+- Per-hop dampening (~0.7 with circuit breakers) vs amplification (~1.2-1.8×)
+- 1-2 tick propagation delay (not instant)
+- Circuit breaker state machine: CLOSED → OPEN → HALF_OPEN → CLOSED
+
+Sources: Google SRE Book, Netflix Hystrix, Docs/DataResearch.md Answer 3.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Circuit breaker state machine
+# ---------------------------------------------------------------------------
+
+
+class BreakerState(str, Enum):
+    CLOSED = "CLOSED"
+    OPEN = "OPEN"
+    HALF_OPEN = "HALF_OPEN"
+
+
+@dataclass
+class CircuitBreaker:
+    """Per-edge circuit breaker with rolling error window."""
+
+    state: BreakerState = BreakerState.CLOSED
+
+    # Config (tunable by agent via tune_config)
+    error_threshold: float = 0.5      # Error rate to trip OPEN
+    cooldown_ticks: int = 5           # Ticks to stay OPEN before half-open
+    half_open_success_threshold: int = 3  # Successes needed to close
+
+    # Runtime state
+    ticks_in_current_state: int = 0
+    error_window: List[float] = field(default_factory=list)
+    window_size: int = 5
+    half_open_successes: int = 0
+
+    def record_error_rate(self, error_rate: float) -> None:
+        """Record an error rate observation and potentially transition state."""
+        self.error_window.append(error_rate)
+        if len(self.error_window) > self.window_size:
+            self.error_window = self.error_window[-self.window_size:]
+        self.ticks_in_current_state += 1
+
+    def tick(self, current_error_rate: float, rng: random.Random) -> BreakerState:
+        """Advance the circuit breaker state machine by one tick."""
+        self.record_error_rate(current_error_rate)
+        avg_error = sum(self.error_window) / len(self.error_window) if self.error_window else 0.0
+
+        if self.state == BreakerState.CLOSED:
+            if avg_error >= self.error_threshold:
+                self.state = BreakerState.OPEN
+                self.ticks_in_current_state = 0
+                self.half_open_successes = 0
+
+        elif self.state == BreakerState.OPEN:
+            if self.ticks_in_current_state >= self.cooldown_ticks:
+                self.state = BreakerState.HALF_OPEN
+                self.ticks_in_current_state = 0
+                self.half_open_successes = 0
+
+        elif self.state == BreakerState.HALF_OPEN:
+            if current_error_rate < self.error_threshold * 0.5:
+                self.half_open_successes += 1
+                if self.half_open_successes >= self.half_open_success_threshold:
+                    self.state = BreakerState.CLOSED
+                    self.ticks_in_current_state = 0
+                    self.error_window.clear()
+            else:
+                # Probe failed — go back to OPEN
+                self.state = BreakerState.OPEN
+                self.ticks_in_current_state = 0
+                self.half_open_successes = 0
+
+        return self.state
+
+    @property
+    def dampening_factor(self) -> float:
+        """How much this breaker dampens downstream error propagation."""
+        if self.state == BreakerState.OPEN:
+            return 0.05   # Nearly all errors blocked (fail-fast)
+        elif self.state == BreakerState.HALF_OPEN:
+            return 0.3    # Some probe traffic gets through
+        else:
+            return 1.0    # No dampening
+
+
+# ---------------------------------------------------------------------------
+# Queueing theory functions
+# ---------------------------------------------------------------------------
+
+
+def compute_utilisation(
+    arrival_rate: float,
+    service_time: float,
+    thread_pool_size: int,
+) -> float:
+    """
+    Little's Law: L = λ × S (average items in system).
+    Utilisation ρ = L / T where T is thread pool size.
+    When ρ → 1.0, latency blows up nonlinearly (M/M/c queueing).
+    """
+    L = arrival_rate * service_time
+    T = max(1, thread_pool_size)
+    rho = L / T
+    return min(rho, 1.0)  # Cap at 1.0 (saturated)
+
+
+def compute_queueing_latency_multiplier(rho: float) -> float:
+    """
+    Approximate M/M/1 queueing delay multiplier.
+    As ρ → 1, response time → ∞.
+    Uses 1/(1-ρ) approximation with a cap to avoid infinity.
+    """
+    if rho >= 0.99:
+        return 50.0   # ~50x baseline latency (effectively down)
+    if rho >= 0.95:
+        return 20.0   # ~20x
+    if rho >= 0.90:
+        return 10.0   # ~10x
+    if rho >= 0.80:
+        return 5.0    # ~5x
+    if rho < 0.01:
+        return 1.0    # No queueing
+    return 1.0 / (1.0 - rho)
+
+
+def compute_retry_amplification(
+    failure_probability: float,
+    max_retries: int,
+) -> float:
+    """
+    Expected number of attempts with retries.
+    E[attempts] = (1 - p^(R+1)) / (1 - p)
+    where p = failure probability, R = max retries.
+    """
+    p = max(0.0, min(1.0, failure_probability))
+    if p < 0.001:
+        return 1.0  # No failures, no retries
+    if p > 0.999:
+        return float(max_retries + 1)  # Every attempt fails
+
+    R = max(0, max_retries)
+    return (1.0 - p ** (R + 1)) / (1.0 - p)
+
+
+# ---------------------------------------------------------------------------
+# Propagation engine
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ServiceRuntimeState:
+    """Mutable runtime state for one service during simulation."""
+
+    service_id: str
+
+    # --- Current metrics (updated each tick) ---
+    error_rate: float = 0.0
+    latency_p50_ms: float = 20.0
+    latency_p95_ms: float = 50.0
+    latency_p99_ms: float = 100.0
+    throughput_rps: float = 100.0
+    cpu_pct: float = 15.0
+    memory_pct: float = 30.0
+    connection_pool_usage_pct: float = 10.0
+
+    # --- Queueing model state ---
+    arrival_rate: float = 100.0       # λ — requests/tick
+    service_time_local: float = 0.05  # S_local — seconds per request
+    thread_pool_size: int = 50        # T — max concurrent
+    utilisation: float = 0.0          # ρ = L/T
+
+    # --- Deployment ---
+    replicas: int = 2
+    version: str = "v1.0.0"
+    previous_version: Optional[str] = None
+    status: str = "healthy"  # healthy | degraded | critical | down
+
+    # --- Config (tunable by agent) ---
+    timeout_ms: int = 5000
+    retry_max: int = 3
+    retry_backoff: bool = False
+    pool_size: int = 20
+
+    # --- Circuit breakers (per-dependency) ---
+    circuit_breakers: Dict[str, CircuitBreaker] = field(default_factory=dict)
+
+    # --- Failure state ---
+    has_active_failure: bool = False
+    failure_ticks: int = 0
+    propagation_error_rate: float = 0.0  # Error rate from upstream propagation
+
+    def compute_status(self) -> str:
+        """Derive health status from metrics."""
+        if self.error_rate >= 0.90:
+            return "down"
+        elif self.error_rate >= 0.30 or self.latency_p99_ms >= 5000:
+            return "critical"
+        elif self.error_rate >= 0.05 or self.latency_p99_ms >= 1000:
+            return "degraded"
+        else:
+            return "healthy"
+
+    def update_latency_percentiles(self, base_p99: float, multiplier: float, rng: random.Random) -> None:
+        """Update p50/p95/p99 from a base p99 and multiplier, with natural noise."""
+        noise = rng.uniform(0.95, 1.05)
+        self.latency_p99_ms = max(1.0, base_p99 * multiplier * noise)
+        self.latency_p95_ms = self.latency_p99_ms * rng.uniform(0.60, 0.85)
+        self.latency_p50_ms = self.latency_p95_ms * rng.uniform(0.30, 0.50)
+
+
+def propagate_failures(
+    services: Dict[str, ServiceRuntimeState],
+    adjacency: Dict[str, List[str]],
+    reverse_adjacency: Dict[str, List[str]],
+    edge_activation: Dict[Tuple[str, str], float],
+    rng: random.Random,
+    propagation_delay: int = 1,
+    current_tick: int = 0,
+) -> None:
+    """
+    Propagate failure effects through the dependency graph for one tick.
+
+    Each service that has errors causes downstream impact on its callers:
+    1. Caller's arrival rate may spike (retries, cache miss stampede)
+    2. Caller's service time increases (waiting on slow downstream)
+    3. Caller's thread pool fills up (blocked threads)
+    4. Circuit breakers may trip (dampening propagation)
+
+    This modifies ServiceRuntimeState in-place.
+    """
+    # Process in reverse topological order: infra → business → edge
+    # So downstream failures propagate to upstream callers
+    for service_id, state in services.items():
+        if state.error_rate < 0.01:
+            continue  # Healthy — no propagation from this service
+
+        # Who calls this service? (reverse edges = callers)
+        callers = reverse_adjacency.get(service_id, [])
+
+        for caller_id in callers:
+            caller = services.get(caller_id)
+            if caller is None:
+                continue
+
+            edge_key = (caller_id, service_id)
+            activation_prob = edge_activation.get(edge_key, 1.0)
+
+            # Is this edge active this tick?
+            if rng.random() > activation_prob:
+                continue  # Edge not active — this dependency not called
+
+            # Get circuit breaker for this edge
+            if service_id not in caller.circuit_breakers:
+                caller.circuit_breakers[service_id] = CircuitBreaker()
+            breaker = caller.circuit_breakers[service_id]
+
+            # Update circuit breaker state
+            breaker.tick(state.error_rate, rng)
+            dampening = breaker.dampening_factor
+
+            # --- Compute propagated impact ---
+
+            # 1. Error propagation (dampened by circuit breaker)
+            propagated_error = state.error_rate * dampening * rng.uniform(0.5, 0.9)
+            caller.propagation_error_rate = max(
+                caller.propagation_error_rate,
+                propagated_error,
+            )
+
+            # 2. Retry amplification (increases arrival rate)
+            if dampening > 0.1:  # Only retries if breaker isn't fully open
+                retry_mult = compute_retry_amplification(
+                    state.error_rate * dampening,
+                    caller.retry_max,
+                )
+                caller.arrival_rate *= min(retry_mult, 3.0)  # Cap at 3x
+
+            # 3. Latency propagation (waiting on slow downstream)
+            if state.latency_p99_ms > 500 and dampening > 0.1:
+                downstream_wait = state.latency_p99_ms * dampening * 0.001  # ms → seconds
+                caller.service_time_local += downstream_wait * 0.5  # Partial impact
+
+    # --- After propagation: update utilisation and derived metrics ---
+    for service_id, state in services.items():
+        # Recompute utilisation
+        state.utilisation = compute_utilisation(
+            state.arrival_rate / max(1, state.replicas),  # Per-replica arrival rate
+            state.service_time_local,
+            state.thread_pool_size,
+        )
+
+        # Apply queueing delay to latency
+        q_mult = compute_queueing_latency_multiplier(state.utilisation)
+        if q_mult > 1.1:
+            base_p99 = 100.0  # Baseline p99 in ms
+            state.update_latency_percentiles(base_p99, q_mult, rng)
+
+        # Combine direct failure error rate with propagation error rate
+        combined_error = max(state.error_rate, state.propagation_error_rate)
+        state.error_rate = min(1.0, combined_error)
+
+        # Compute throughput (inverse of error rate, scaled by arrival)
+        state.throughput_rps = state.arrival_rate * (1.0 - state.error_rate) / max(1, state.replicas)
+
+        # Update status
+        state.status = state.compute_status()
+
+        # Reset per-tick propagation accumulator
+        state.propagation_error_rate = 0.0