stateDiagram-v2
    [*] --> MONITORING
    MONITORING --> READY: no fault
    MONITORING --> FAULT_DETECTED: symptom / timeout / lost heartbeat
    FAULT_DETECTED --> SAFE_STOPPED: stop all ordinary outputs
    SAFE_STOPPED --> DIAGNOSING: snapshot preserved
    DIAGNOSING --> RECOVERY_REQUIRED: diagnosis + evidence list
    RECOVERY_REQUIRED --> RECOVERY_REQUIRED: incomplete gates
    RECOVERY_REQUIRED --> READY: operator ack + cause removed + reconciled + area clear

# safe-smoke
def may_recover(*, operator_ack: bool, cause_removed: bool, reconciled: bool, area_clear: bool) -> bool:
    return operator_ack and cause_removed and reconciled and area_clear

assert not may_recover(operator_ack=False, cause_removed=True, reconciled=True, area_clear=True)
assert not may_recover(operator_ack=True, cause_removed=True, reconciled=False, area_clear=True)
assert may_recover(operator_ack=True, cause_removed=True, reconciled=True, area_clear=True)
print("safe-smoke: four recovery gates PASS")

[
  {"id":"network_lost","service":"network","available":false,"expected":"STOP_AND_ERROR"},
  {"id":"robot_no_ack","service":"robot","available":true,"command_ack":false,"elapsed_ticks":4,"timeout_ticks":3,"expected":"STOP_AND_ERROR"},
  {"id":"mechanism_timeout","service":"mechanism","completed":false,"elapsed_ticks":5,"timeout_ticks":4,"expected":"STOP_AND_ERROR"},
  {"id":"unknown_fault","service":"unknown","code":"UNMAPPED","expected":"STOP_AND_ERROR"},
  {"id":"restart_while_active","service":"orchestrator","restart":true,"cycle_active":true,"expected":"RECOVERY_REQUIRED"}
]

from __future__ import annotations

import argparse
import json
from dataclasses import asdict, dataclass, field
from enum import Enum
from pathlib import Path


class State(str, Enum):
    MONITORING="MONITORING"; FAULT_DETECTED="FAULT_DETECTED"; SAFE_STOPPED="SAFE_STOPPED"
    DIAGNOSING="DIAGNOSING"; RECOVERY_REQUIRED="RECOVERY_REQUIRED"; READY="READY"


EVIDENCE = {
    "SENSOR_WIRE_OR_CHANNEL_FAULT": ["raw channels", "active-level config", "wiring inspection by operator"],
    "CAMERA_LOST": ["camera service health", "last frame timestamp", "service log"],
    "DATABASE_LOST": ["DB health", "transaction status", "storage log"],
    "ROBOT_LINK_LOST": ["last feedback", "actual pose by approved read-only check", "queue status"],
    "CONVEYOR_JAM": ["command/feedback history", "sensor history", "operator visual inspection"],
    "FEEDER_JAM": ["command/feedback history", "part sensor history", "operator visual inspection"],
    "NETWORK_LOST": ["local link status", "service heartbeat", "network log"],
    "ROBOT_NO_ACK": ["goal id", "ack timeout", "actual robot state"],
    "MECHANISM_TIMEOUT": ["command id", "completion signal", "operator inspection"],
    "RESTART_ACTIVE": ["last committed state", "physical item location", "cycle event log"],
    "UNKNOWN_FAULT": ["full snapshot", "raw log", "maintainer review"],
}


@dataclass
class Diagnosis:
    scenario_id: str
    state: str
    code: str | None
    safe_outputs: bool
    evidence: list[str]
    transitions: list[str] = field(default_factory=list)


def classify(case: dict) -> str | None:
    sid = str(case["id"])
    if sid in ("sensor_normal_low", "sensor_normal_high", "inverse_logic_nc"):
        return None
    if sid in ("wire_break", "short_to_0v", "short_to_24v"):
        return "SENSOR_WIRE_OR_CHANNEL_FAULT"
    direct = {
        "camera_lost":"CAMERA_LOST", "database_lost":"DATABASE_LOST",
        "robot_connection_lost":"ROBOT_LINK_LOST", "conveyor_jam":"CONVEYOR_JAM",
        "feeder_jam":"FEEDER_JAM", "network_lost":"NETWORK_LOST",
        "robot_no_ack":"ROBOT_NO_ACK", "mechanism_timeout":"MECHANISM_TIMEOUT",
        "restart_while_active":"RESTART_ACTIVE", "unknown_fault":"UNKNOWN_FAULT",
    }
    return direct.get(sid, "UNKNOWN_FAULT")


class DiagnosticFSM:
    def __init__(self) -> None:
        self.state = State.MONITORING
        self.outputs = {"feeder":"STOP", "conveyor":"STOP", "robot":"NO_NEW_GOAL", "gripper":"STOP"}
        self.log: list[str] = []

    def move(self, target: State, reason: str) -> None:
        self.log.append(f"{self.state.value}->{target.value}:{reason}")
        self.state = target

    def inspect(self, case: dict) -> Diagnosis:
        code = classify(case)
        if code is None:
            self.move(State.READY, "no-fault")
            return Diagnosis(str(case["id"]), self.state.value, None, True, [], list(self.log))
        self.move(State.FAULT_DETECTED, code)
        self.move(State.SAFE_STOPPED, "ordinary-outputs-stopped")
        self.move(State.DIAGNOSING, "snapshot-preserved")
        self.move(State.RECOVERY_REQUIRED, code)
        safe = all(value in ("STOP", "NO_NEW_GOAL") for value in self.outputs.values())
        return Diagnosis(str(case["id"]), self.state.value, code, safe, EVIDENCE[code], list(self.log))

    def recover(self, operator_ack: bool, cause_removed: bool, reconciled: bool, area_clear: bool) -> bool:
        if self.state is not State.RECOVERY_REQUIRED:
            return False
        if not (operator_ack and cause_removed and reconciled and area_clear):
            return False
        self.move(State.READY, "manual-recovery-complete")
        return True


def main() -> int:
    p = argparse.ArgumentParser()
    p.add_argument("--base", type=Path, required=True); p.add_argument("--extra", type=Path, required=True)
    p.add_argument("--out", type=Path, required=True); args = p.parse_args()
    base = json.loads(args.base.read_text(encoding="utf-8"))
    if base.get("scope") != "simulation_only":
        raise ValueError("base scenarios are not marked simulation_only")
    cases = list(base["scenarios"]) + json.loads(args.extra.read_text(encoding="utf-8"))
    results: list[Diagnosis] = []
    for case in cases:
        fsm = DiagnosticFSM(); result = fsm.inspect(case); results.append(result)
        if result.state == "RECOVERY_REQUIRED":
            assert result.safe_outputs and result.evidence
            assert not fsm.recover(False, True, True, True)
            assert fsm.recover(True, True, True, True)
    for result in results:
        expected_ready = result.scenario_id in ("sensor_normal_low", "sensor_normal_high", "inverse_logic_nc")
        assert (result.state == "READY") == expected_ready
    args.out.write_text(json.dumps([asdict(r) for r in results], ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"PASS: ready={sum(r.state == 'READY' for r in results)} recovery={sum(r.state == 'RECOVERY_REQUIRED' for r in results)}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

python lab23_diagnostics.py --base data/fault-scenarios.json --extra lab23-extra-cases.json --out lab23-results.json