worldstate-check 0.1.1__py3-none-any.whl

worldstate_check/__init__.py

@@ -0,0 +1,3 @@
+"""WorldState Check package."""
+
+__version__ = "0.1.0"

worldstate_check/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

worldstate_check/checks/__init__.py

@@ -0,0 +1,15 @@
+from .command import run_command_check
+from .file import run_file_check
+from .http import run_http_check
+from .json_check import run_json_check
+from .metric import run_metric_check
+from .tcp import run_tcp_check
+
+CHECK_RUNNERS = {
+    "file": run_file_check,
+    "json": run_json_check,
+    "metric": run_metric_check,
+    "http": run_http_check,
+    "tcp": run_tcp_check,
+    "command": run_command_check,
+}

worldstate_check/checks/base.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from worldstate_check.models import CheckResult, CheckStatus, VerificationContext
+
+
+def timed_result(
+    check: dict[str, Any],
+    fn: Callable[[], tuple[CheckStatus, str, Any, Any, dict[str, Any], str | None]],
+) -> CheckResult:
+    started = time.perf_counter()
+    status, summary, expected, observed, evidence, error = fn()
+    return CheckResult(
+        check_id=check["id"],
+        check_type=check["type"],
+        required=check.get("required", True),
+        status=status,
+        summary=summary,
+        expected=expected,
+        observed=observed,
+        evidence=evidence,
+        error=error,
+        duration_ms=(time.perf_counter() - started) * 1000,
+    )
+
+
+def unknown(check: dict[str, Any], message: str, *, evidence: dict[str, Any] | None = None) -> CheckResult:
+    return CheckResult(
+        check_id=check["id"],
+        check_type=check["type"],
+        required=check.get("required", True),
+        status=CheckStatus.UNKNOWN,
+        summary=message,
+        evidence=evidence or {},
+        error=message,
+    )

worldstate_check/checks/command.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any
+
+from worldstate_check.errors import PathBoundaryError
+from worldstate_check.models import CheckStatus, VerificationContext
+from worldstate_check.util import resolve_path
+
+from .base import timed_result, unknown
+
+
+def run_command_check(check: dict[str, Any], ctx: VerificationContext):
+    if not ctx.allow_command:
+        return unknown(check, "command checks are disabled; pass --allow-command for a trusted specification")
+    try:
+        cwd = resolve_path(ctx.root, check.get("cwd", "."), ctx.allow_outside_root)
+    except PathBoundaryError as exc:
+        return unknown(check, str(exc))
+
+    def evaluate():
+        max_bytes = check.get("max_output_bytes", 65_536)
+        timeout = float(check.get("timeout_seconds", 10.0))
+        env = {"PATH": os.environ.get("PATH", ""), "HOME": os.environ.get("HOME", "")}
+        try:
+            proc = subprocess.run(
+                check["argv"],
+                cwd=cwd,
+                env=env,
+                capture_output=True,
+                text=False,
+                shell=False,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return CheckStatus.FAIL, "verification command timed out", {"timeout_seconds": timeout}, None, {"cwd": str(cwd)}, None
+        except (OSError, ValueError) as exc:
+            return CheckStatus.UNKNOWN, "verification command could not be started", None, None, {"cwd": str(cwd)}, str(exc)
+
+        stdout_bytes = proc.stdout[: max_bytes + 1]
+        stderr_bytes = proc.stderr[: max_bytes + 1]
+        if len(stdout_bytes) > max_bytes or len(stderr_bytes) > max_bytes:
+            return (
+                CheckStatus.UNKNOWN,
+                "verification command output exceeds configured evidence limit",
+                None,
+                {"exit_code": proc.returncode},
+                {"cwd": str(cwd), "max_output_bytes": max_bytes},
+                None,
+            )
+        stdout = stdout_bytes.decode("utf-8", errors="replace")
+        stderr = stderr_bytes.decode("utf-8", errors="replace")
+        expected: dict[str, Any] = {}
+        observed: dict[str, Any] = {"exit_code": proc.returncode}
+        failures: list[str] = []
+        if "exit_code" in check:
+            expected["exit_code"] = check["exit_code"]
+            if proc.returncode != check["exit_code"]:
+                failures.append(f"exit_code={proc.returncode}")
+        if "stdout_contains" in check:
+            expected["stdout_contains"] = check["stdout_contains"]
+            matched = check["stdout_contains"] in stdout
+            observed["stdout_contains"] = matched
+            if not matched:
+                failures.append("required stdout text missing")
+        if "stderr_contains" in check:
+            expected["stderr_contains"] = check["stderr_contains"]
+            matched = check["stderr_contains"] in stderr
+            observed["stderr_contains"] = matched
+            if not matched:
+                failures.append("required stderr text missing")
+
+        evidence = {
+            "argv": check["argv"],
+            "cwd": str(cwd),
+            "stdout_excerpt": stdout[-2000:],
+            "stderr_excerpt": stderr[-2000:],
+        }
+        if failures:
+            return CheckStatus.FAIL, "; ".join(failures), expected, observed, evidence, None
+        return CheckStatus.PASS, "command postcondition satisfied", expected, observed, evidence, None
+
+    return timed_result(check, evaluate)

worldstate_check/checks/file.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from worldstate_check.errors import PathBoundaryError
+from worldstate_check.models import CheckStatus, VerificationContext
+from worldstate_check.util import resolve_path
+
+from .base import timed_result, unknown
+
+
+def run_file_check(check: dict[str, Any], ctx: VerificationContext):
+    try:
+        path = resolve_path(ctx.root, check["path"], ctx.allow_outside_root)
+    except PathBoundaryError as exc:
+        return unknown(check, str(exc))
+
+    def evaluate():
+        exists = path.exists()
+        expected: dict[str, Any] = {}
+        observed: dict[str, Any] = {"exists": exists}
+        evidence: dict[str, Any] = {"path": str(path)}
+        failures: list[str] = []
+
+        if "exists" in check:
+            expected["exists"] = check["exists"]
+            if exists != check["exists"]:
+                failures.append(f"exists={exists}")
+
+        content: str | None = None
+        if any(k in check for k in {"contains", "not_contains"}):
+            if not exists or not path.is_file():
+                failures.append("file content unavailable")
+            else:
+                max_bytes = check.get("max_read_bytes", 1_048_576)
+                size = path.stat().st_size
+                evidence["size_bytes"] = size
+                if size > max_bytes:
+                    return (
+                        CheckStatus.UNKNOWN,
+                        f"file exceeds max_read_bytes ({size} > {max_bytes})",
+                        expected,
+                        observed,
+                        evidence,
+                        "file too large for configured text assertion",
+                    )
+                try:
+                    content = path.read_text(encoding="utf-8")
+                except (OSError, UnicodeDecodeError) as exc:
+                    return CheckStatus.UNKNOWN, "could not read file as UTF-8", expected, observed, evidence, str(exc)
+
+        if "contains" in check:
+            expected["contains"] = check["contains"]
+            matched = content is not None and check["contains"] in content
+            observed["contains"] = matched
+            if not matched:
+                failures.append("required text missing")
+
+        if "not_contains" in check:
+            expected["not_contains"] = check["not_contains"]
+            matched = content is not None and check["not_contains"] not in content
+            observed["not_contains"] = matched
+            if not matched:
+                failures.append("forbidden text present")
+
+        if "sha256" in check:
+            expected["sha256"] = check["sha256"].lower()
+            if not exists or not path.is_file():
+                failures.append("sha256 unavailable")
+            else:
+                digest = hashlib.sha256()
+                try:
+                    with path.open("rb") as handle:
+                        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                            digest.update(chunk)
+                except OSError as exc:
+                    return CheckStatus.UNKNOWN, "could not hash file", expected, observed, evidence, str(exc)
+                observed["sha256"] = digest.hexdigest()
+                if observed["sha256"] != expected["sha256"]:
+                    failures.append("sha256 mismatch")
+
+        if failures:
+            return CheckStatus.FAIL, "; ".join(failures), expected, observed, evidence, None
+        return CheckStatus.PASS, "file postcondition satisfied", expected, observed, evidence, None
+
+    return timed_result(check, evaluate)

worldstate_check/checks/http.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from worldstate_check.errors import SpecError
+from worldstate_check.models import CheckStatus, VerificationContext
+from worldstate_check.util import compare_value, extract_dotted
+
+from .base import timed_result
+
+
+def run_http_check(check: dict[str, Any], ctx: VerificationContext):
+    del ctx
+
+    def evaluate():
+        timeout = float(check.get("timeout_seconds", 3.0))
+        request = urllib.request.Request(check["url"], method="GET", headers={"User-Agent": "worldstate-check/0.1"})
+        evidence: dict[str, Any] = {"url": check["url"]}
+        try:
+            response = urllib.request.urlopen(request, timeout=timeout)
+            status = response.status
+            body_bytes = response.read(1_048_577)
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            body_bytes = exc.read(1_048_577)
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            return CheckStatus.FAIL, "HTTP endpoint could not be reached", None, None, evidence, str(exc)
+
+        if len(body_bytes) > 1_048_576:
+            return CheckStatus.UNKNOWN, "HTTP response exceeds 1 MiB evidence limit", None, status, evidence, None
+        body = body_bytes.decode("utf-8", errors="replace")
+        observed: dict[str, Any] = {"status": status}
+        expected: dict[str, Any] = {}
+        failures: list[str] = []
+
+        if "status" in check:
+            expected["status"] = check["status"]
+            if status != check["status"]:
+                failures.append(f"status={status}")
+        if "text_contains" in check:
+            expected["text_contains"] = check["text_contains"]
+            matched = check["text_contains"] in body
+            observed["text_contains"] = matched
+            if not matched:
+                failures.append("required response text missing")
+        if "json_field" in check:
+            try:
+                payload = json.loads(body)
+                value = extract_dotted(payload, check["json_field"])
+                matched, expected_value = compare_value(value, check["operator"], check)
+            except (json.JSONDecodeError, KeyError, ValueError, SpecError) as exc:
+                return CheckStatus.UNKNOWN, "HTTP JSON assertion could not be evaluated", expected, observed, evidence, str(exc)
+            expected["json"] = {"field": check["json_field"], "value": expected_value, "operator": check["operator"]}
+            observed["json"] = {"field": check["json_field"], "value": value}
+            if not matched:
+                failures.append("JSON response postcondition not satisfied")
+
+        evidence["body_bytes"] = len(body_bytes)
+        if failures:
+            return CheckStatus.FAIL, "; ".join(failures), expected, observed, evidence, None
+        return CheckStatus.PASS, "HTTP postcondition satisfied", expected, observed, evidence, None
+
+    return timed_result(check, evaluate)

worldstate_check/checks/json_check.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from worldstate_check.errors import PathBoundaryError, SpecError
+from worldstate_check.models import CheckStatus, VerificationContext
+from worldstate_check.util import compare_value, evidence_path, extract_dotted, read_text_limited, resolve_path, strict_json_loads
+
+from .base import timed_result, unknown
+
+
+def run_json_check(check: dict[str, Any], ctx: VerificationContext):
+    try:
+        path = resolve_path(ctx.root, check["path"], ctx.allow_outside_root)
+    except PathBoundaryError as exc:
+        return unknown(check, str(exc))
+
+    def evaluate():
+        evidence = {"path": evidence_path(path, ctx.root), "field": check["field"]}
+        try:
+            raw = read_text_limited(path, int(check.get("max_read_bytes", 1_048_576)))
+            data = strict_json_loads(raw)
+        except FileNotFoundError:
+            return CheckStatus.FAIL, "JSON file does not exist", None, None, evidence, None
+        except (OSError, UnicodeDecodeError, ValueError) as exc:
+            return CheckStatus.UNKNOWN, "could not parse JSON evidence", None, None, evidence, str(exc)
+        try:
+            observed = extract_dotted(data, check["field"])
+        except KeyError:
+            return CheckStatus.FAIL, f"JSON field not found: {check['field']}", None, None, evidence, None
+        try:
+            matched, expected = compare_value(observed, check["operator"], check)
+        except (ValueError, SpecError) as exc:
+            return CheckStatus.UNKNOWN, "JSON comparison could not be evaluated", None, observed, evidence, str(exc)
+        if matched:
+            return CheckStatus.PASS, "JSON postcondition satisfied", expected, observed, evidence, None
+        return CheckStatus.FAIL, "JSON postcondition not satisfied", expected, observed, evidence, None
+
+    return timed_result(check, evaluate)

worldstate_check/checks/metric.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import csv
+import io
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from worldstate_check.errors import PathBoundaryError, SpecError
+from worldstate_check.models import CheckStatus, VerificationContext
+from worldstate_check.util import (
+    compare_value,
+    evidence_path,
+    extract_dotted,
+    freshness_age_seconds,
+    read_text_limited,
+    resolve_path,
+    strict_json_loads,
+)
+
+from .base import timed_result, unknown
+
+DEFAULT_MAX_TELEMETRY_BYTES = 16 * 1024 * 1024
+
+
+def run_metric_check(check: dict[str, Any], ctx: VerificationContext):
+    source = check["source"]
+    try:
+        path = resolve_path(ctx.root, source["path"], ctx.allow_outside_root)
+    except PathBoundaryError as exc:
+        return unknown(check, str(exc))
+
+    def evaluate():
+        evidence: dict[str, Any] = {"path": evidence_path(path, ctx.root), "source_type": source["type"]}
+        try:
+            observed, timestamp_value = _read_source(path, source)
+        except FileNotFoundError:
+            return CheckStatus.FAIL, "telemetry source does not exist", None, None, evidence, None
+        except (OSError, UnicodeDecodeError, csv.Error, KeyError, ValueError) as exc:
+            return CheckStatus.UNKNOWN, "could not read telemetry evidence", None, None, evidence, str(exc)
+
+        if "max_age_seconds" in source:
+            try:
+                age = freshness_age_seconds(timestamp_value, datetime.now(timezone.utc))
+            except (ValueError, OSError, OverflowError) as exc:
+                return CheckStatus.UNKNOWN, "could not evaluate telemetry freshness", None, observed, evidence, str(exc)
+            evidence["age_seconds"] = round(age, 3)
+            evidence["max_age_seconds"] = source["max_age_seconds"]
+            if age > float(source["max_age_seconds"]):
+                return (
+                    CheckStatus.FAIL,
+                    "telemetry is stale",
+                    {"max_age_seconds": source["max_age_seconds"]},
+                    {"age_seconds": round(age, 3), "value": observed},
+                    evidence,
+                    None,
+                )
+
+        try:
+            matched, expected = compare_value(observed, check["operator"], check)
+        except (ValueError, SpecError) as exc:
+            return CheckStatus.UNKNOWN, "metric comparison could not be evaluated", None, observed, evidence, str(exc)
+        if matched:
+            return CheckStatus.PASS, "metric postcondition satisfied", expected, observed, evidence, None
+        return CheckStatus.FAIL, "metric postcondition not satisfied", expected, observed, evidence, None
+
+    return timed_result(check, evaluate)
+
+
+def _read_source(path: Path, source: dict[str, Any]) -> tuple[Any, Any]:
+    raw = read_text_limited(path, int(source.get("max_read_bytes", DEFAULT_MAX_TELEMETRY_BYTES)))
+    if source["type"] == "json":
+        data = strict_json_loads(raw)
+        observed = extract_dotted(data, source["field"])
+        timestamp = extract_dotted(data, source["timestamp_field"]) if "max_age_seconds" in source else None
+        return observed, timestamp
+
+    reader = csv.DictReader(io.StringIO(raw.lstrip("\ufeff")))
+    if reader.fieldnames is None:
+        raise ValueError("CSV telemetry source has no header")
+    if len(reader.fieldnames) != len(set(reader.fieldnames)):
+        raise ValueError("CSV telemetry source has duplicate column names")
+    row: dict[str, str | None] | None = None
+    for row in reader:
+        if None in row:
+            raise ValueError("CSV telemetry row has more values than the header")
+    if row is None:
+        raise ValueError("CSV telemetry source has no data rows")
+    if source["column"] not in row:
+        raise KeyError(source["column"])
+    observed = _coerce_scalar(row[source["column"]])
+    timestamp = row[source["timestamp_column"]] if "max_age_seconds" in source else None
+    return observed, timestamp
+
+
+def _coerce_scalar(value: str | None) -> Any:
+    if value is None:
+        raise ValueError("CSV telemetry value is missing")
+    stripped = value.strip()
+    lowered = stripped.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    try:
+        if any(c in stripped for c in ".eE"):
+            value_float = float(stripped)
+            if not math.isfinite(value_float):
+                return stripped
+            return value_float
+        return int(stripped)
+    except ValueError:
+        return stripped

worldstate_check/checks/tcp.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import socket
+from typing import Any
+
+from worldstate_check.models import CheckStatus, VerificationContext
+
+from .base import timed_result, unknown
+
+
+def run_tcp_check(check: dict[str, Any], ctx: VerificationContext):
+    if not ctx.allow_network:
+        return unknown(check, "network checks are disabled; pass --allow-network for a trusted specification")
+
+    def evaluate():
+        expected = check.get("reachable", True)
+        timeout = float(check.get("timeout_seconds", 2.0))
+        evidence = {"host": check["host"], "port": check["port"]}
+        try:
+            with socket.create_connection((check["host"], check["port"]), timeout=timeout):
+                reachable = True
+        except OSError as exc:
+            reachable = False
+            evidence["connection_error"] = exc.__class__.__name__
+        status = CheckStatus.PASS if reachable == expected else CheckStatus.FAIL
+        summary = "TCP postcondition satisfied" if status is CheckStatus.PASS else "TCP postcondition not satisfied"
+        return status, summary, expected, reachable, evidence, None
+
+    return timed_result(check, evaluate)

worldstate_check/cli.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .demo import run_demo
+from .engine import verify
+from .errors import SpecError
+from .loader import load_spec
+from .models import VerificationContext, Verdict
+from .report import render_text, report_payload, verify_json_report, write_json_report
+
+EXIT_BY_VERDICT = {
+    Verdict.VERIFIED: 0,
+    Verdict.NOT_VERIFIED: 1,
+    Verdict.UNCERTAIN: 2,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="worldstate-check",
+        description="Verify observed postconditions after an AI agent or autonomous system acts.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    verify_parser = sub.add_parser("verify", help="evaluate a verification specification")
+    verify_parser.add_argument("spec", type=Path)
+    verify_parser.add_argument("--root", type=Path, help="verification root; defaults to the specification directory")
+    verify_parser.add_argument("--allow-outside-root", action="store_true", help="allow file paths outside the verification root")
+    verify_parser.add_argument("--allow-command", action="store_true", help="allow command checks in a trusted specification")
+    verify_parser.add_argument("--allow-network", action="store_true", help="allow HTTP and TCP checks in a trusted specification")
+    verify_parser.add_argument("--wait", type=float, default=0.0, metavar="SECONDS", help="retry until verified or the timeout expires")
+    verify_parser.add_argument("--poll-interval", type=float, default=0.5, metavar="SECONDS")
+    verify_parser.add_argument("--report", type=Path, help="write a JSON evidence report")
+    verify_parser.add_argument("--json", action="store_true", help="print the JSON report instead of text")
+
+    validate_parser = sub.add_parser("validate", help="validate a specification without evaluating it")
+    validate_parser.add_argument("spec", type=Path)
+
+    report_parser = sub.add_parser("verify-report", help="verify the SHA-256 digest of a saved evidence report")
+    report_parser.add_argument("report", type=Path)
+
+    init_parser = sub.add_parser("init", help="write a minimal starter specification")
+    init_parser.add_argument("path", type=Path, nargs="?", default=Path("worldstate.yaml"))
+
+    demo_parser = sub.add_parser("demo", help="run a deterministic synthetic example")
+    demo_parser.add_argument("--scenario", choices=["verified", "partial"], default="partial")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "validate":
+            load_spec(args.spec)
+            print(f"VALID: {args.spec}")
+            return 0
+        if args.command == "verify-report":
+            try:
+                valid = verify_json_report(args.report)
+            except (OSError, json.JSONDecodeError) as exc:
+                print(f"ERROR: could not read report: {exc}", file=sys.stderr)
+                return 2
+            print(f"{'VALID' if valid else 'INVALID'}: {args.report}")
+            return 0 if valid else 1
+        if args.command == "init":
+            return _init_spec(args.path)
+        if args.command == "demo":
+            return EXIT_BY_VERDICT[run_demo(args.scenario)]
+        if args.command == "verify":
+            return _verify_command(args)
+    except SpecError as exc:
+        print(f"SPEC ERROR: {exc}", file=sys.stderr)
+        return 2
+    except (ValueError, OSError, RuntimeError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+def _verify_command(args: argparse.Namespace) -> int:
+    spec_path = args.spec.resolve()
+    spec = load_spec(spec_path)
+    root = (args.root.resolve() if args.root else spec_path.parent)
+    ctx = VerificationContext(
+        spec_path=spec_path,
+        root=root,
+        allow_outside_root=args.allow_outside_root,
+        allow_command=args.allow_command,
+        allow_network=args.allow_network,
+    )
+    report = verify(spec, ctx, wait_seconds=args.wait, poll_interval=args.poll_interval)
+    if args.report:
+        write_json_report(report, args.report)
+    if args.json:
+        print(json.dumps(report_payload(report), indent=2, sort_keys=True))
+    else:
+        print(render_text(report))
+        if args.report:
+            print(f"Report: {args.report.resolve()}")
+    return EXIT_BY_VERDICT[report.verdict]
+
+
+def _init_spec(path: Path) -> int:
+    if path.exists():
+        print(f"ERROR: refusing to overwrite existing file: {path}", file=sys.stderr)
+        return 2
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        """version: 1\ntask: verify-outcome\nchecks:\n  - id: result-file\n    type: file\n    path: result.json\n    exists: true\n\n  - id: result-state\n    type: json\n    path: result.json\n    field: status\n    operator: eq\n    value: complete\n""",
+        encoding="utf-8",
+    )
+    print(f"Created {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

worldstate_check/demo.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from .engine import verify
+from .models import VerificationContext, Verdict
+from .report import render_text
+
+
+def run_demo(scenario: str = "partial") -> Verdict:
+    if scenario not in {"verified", "partial"}:
+        raise ValueError("scenario must be verified or partial")
+    with tempfile.TemporaryDirectory(prefix="worldstate-check-") as raw:
+        root = Path(raw)
+        (root / "command-ack.txt").write_text("SAFE_MODE_ACK\n", encoding="utf-8")
+        attitude = 1.8 if scenario == "verified" else 14.7
+        telemetry = {
+            "mode": "SAFE",
+            "payload": {"power": "off"},
+            "attitude": {"error_deg": attitude},
+            "battery": {"soc": 71.0},
+        }
+        (root / "telemetry.json").write_text(json.dumps(telemetry), encoding="utf-8")
+        spec = {
+            "version": 1,
+            "task": "enter-safe-mode",
+            "checks": [
+                {"id": "command-ack", "type": "file", "path": "command-ack.txt", "contains": "SAFE_MODE_ACK"},
+                {"id": "payload-power", "type": "json", "path": "telemetry.json", "field": "payload.power", "operator": "eq", "value": "off"},
+                {
+                    "id": "attitude-error",
+                    "type": "metric",
+                    "source": {"type": "json", "path": "telemetry.json", "field": "attitude.error_deg"},
+                    "operator": "lte",
+                    "value": 3.0,
+                },
+                {
+                    "id": "battery-soc",
+                    "type": "metric",
+                    "source": {"type": "json", "path": "telemetry.json", "field": "battery.soc"},
+                    "operator": "gte",
+                    "value": 25.0,
+                },
+            ],
+        }
+        report = verify(spec, VerificationContext(spec_path=root / "demo.yaml", root=root))
+        print(render_text(report))
+        return report.verdict