Add runtime validation gate and known issues baseline

scripts/validate_runtime_gate.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from known_issues import default_known_issues_path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run the scenario validators with the shared runtime known-issues baseline."
+    )
+    parser.add_argument(
+        "--runtime-root",
+        type=Path,
+        required=True,
+        help="Client runtime root containing assets/.",
+    )
+    parser.add_argument(
+        "--known-issues",
+        type=Path,
+        default=None,
+        help="Optional known issues baseline JSON. Defaults to repo known_issues/runtime_known_issues.json.",
+    )
+    parser.add_argument(
+        "--strict-known-issues",
+        action="store_true",
+        help="Fail when the known-issues baseline contains stale entries not observed anymore.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON output.",
+    )
+    return parser.parse_args()
+
+
+def run_validator(script_path: Path, runtime_root: Path, known_issues: Path, strict_known_issues: bool) -> dict:
+    cmd = [
+        sys.executable,
+        str(script_path),
+        "--runtime-root",
+        str(runtime_root),
+        "--known-issues",
+        str(known_issues),
+        "--json",
+    ]
+    if strict_known_issues:
+        cmd.append("--strict-known-issues")
+    completed = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    if completed.returncode not in (0, 1):
+        raise RuntimeError(
+            f"{script_path.name} failed unexpectedly with rc={completed.returncode}: {completed.stderr or completed.stdout}"
+        )
+    return json.loads(completed.stdout)
+
+
+def main() -> int:
+    args = parse_args()
+    runtime_root = args.runtime_root.resolve()
+    known_issues = (args.known_issues.resolve() if args.known_issues else default_known_issues_path(__file__))
+
+    script_dir = Path(__file__).resolve().parent
+    validators = {
+        "world": script_dir / "validate_runtime_scenarios.py",
+        "actor": script_dir / "validate_actor_scenarios.py",
+        "effect": script_dir / "validate_effect_scenarios.py",
+    }
+
+    results = {
+        name: run_validator(script_path, runtime_root, known_issues, args.strict_known_issues)
+        for name, script_path in validators.items()
+    }
+    ok = all(result["ok"] for result in results.values())
+
+    summary = {
+        "ok": ok,
+        "runtime_root": str(runtime_root),
+        "known_issues_path": str(known_issues),
+        "validators": results,
+    }
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        print(f"ok={ok}")
+        for name, result in results.items():
+            print(
+                f"{name}: ok={result['ok']} unexpected={len(result.get('unexpected_issue_ids', []))} "
+                f"known={len(result.get('known_issue_ids', []))} stale={len(result.get('stale_known_issue_ids', []))}"
+            )
+
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())