rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/hdl_sim/ghdl.py

@@ -0,0 +1,155 @@
+"""GHDL provider: run_hdl_test with assert-line verdicts."""
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_hdl_test"
+_TOOL = "ghdl"
+_ASSERT_RE = re.compile(
+    r"^(.+):(\d+):(\d+):@(\S+):\((\w[\w ]*) (\w+)\): (.*)$")
+
+
+class GhdlAdapter(ToolAdapter):
+    """run_hdl_test via ghdl: analyze, elaborate, run, parse asserts.
+
+    Serves the run_hdl_test operation with tool `ghdl`. Compile
+    diagnostics arrive on stderr; sim assert/report lines arrive
+    on stdout (never merge blindly). PSL verdicts prefer
+    --psl-report JSON; waveforms prefer --vcd/--fst via pywellen.
+
+    Job keys:
+        sources (required): VHDL source paths.
+        top (required): Top entity name.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 120).
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL,
+                "modes": ["analyze", "sim"]}
+
+    def preflight(self, job):
+        """Check operation, sources, top, and ghdl presence.
+
+        Args:
+            job: Solver job with operation run_hdl_test.
+
+        Returns:
+            Checked mapping with binary, sources, top, timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_command
+                for a bad top, invalid_reference for missing
+                sources, missing_dependency when ghdl is absent.
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"GHDL handles {OPERATION}, got {job.get('operation')}.")
+        top = job.get("top")
+        if not isinstance(top, str) or not top:
+            raise AdapterError("invalid_command", f"Bad top: {top!r}.")
+        sources = job.get("sources") or []
+        missing = [s for s in sources if not Path(s).is_file()]
+        if not sources or missing:
+            raise AdapterError(
+                "invalid_reference", f"Sources not found: {missing or sources}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: ghdl not on PATH.")
+        timeout = job.get("timeout_s", 120)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        return {"binary": binary, "sources": list(sources), "top": top,
+                "timeout_s": timeout}
+
+    def execute(self, job):
+        """Analyze, elaborate, and run the top under a timeout.
+
+        Args:
+            job: Solver job with operation run_hdl_test.
+
+        Returns:
+            Native output with exit_code, stdout, stderr, top.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        try:
+            for src in checked["sources"]:
+                proc = subprocess.run(
+                    [checked["binary"], "-a", src], capture_output=True,
+                    text=True, timeout=checked["timeout_s"], cwd=workdir)
+                if proc.returncode != 0:
+                    return {"exit_code": proc.returncode,
+                            "stdout": proc.stdout, "stderr": proc.stderr,
+                            "top": checked["top"]}
+            proc = subprocess.run(
+                [checked["binary"], "-e", checked["top"]],
+                capture_output=True, text=True,
+                timeout=checked["timeout_s"], cwd=workdir)
+            if proc.returncode != 0:
+                return {"exit_code": proc.returncode,
+                        "stdout": proc.stdout, "stderr": proc.stderr,
+                        "top": checked["top"]}
+            proc = subprocess.run(
+                [checked["binary"], "-r", checked["top"]],
+                capture_output=True, text=True,
+                timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "GHDL run timed out.") from exc
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "top": checked["top"]}
+
+    def parse(self, native_output):
+        """Parse ghdl assert lines; errors fail, notes do not.
+
+        Args:
+            native_output: Native output with sim stdout.
+
+        Returns:
+            {total, violations[], source}.
+        """
+        violations = []
+        for line in (native_output.get("stdout") or "").splitlines():
+            match = _ASSERT_RE.match(line.strip())
+            if match is None:
+                continue
+            path, line_no, _col, _time, _kind, sev, msg = match.groups()
+            if sev.lower() in ("note",):
+                continue
+            violations.append({"rule": "assert_" + sev.lower(),
+                               "severity": ("error" if sev.lower() in
+                                            ("error", "failure")
+                                            else "warning"),
+                               "message": msg[:300], "file": path,
+                               "line": int(line_no)})
+        if "simulation failed" in (native_output.get("stdout") or ""):
+            if not violations:
+                violations.append({"rule": "sim_fail", "severity": "error",
+                                   "message": "GHDL simulation failed."})
+        return {"total": len(violations), "violations": violations,
+                "source": "stdout"}

rocket_engine/adapters/hdl_sim/results.py

@@ -0,0 +1,178 @@
+"""HDL-sim v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_hdl_test`` parse shape (``violations[]`` with
+rule, severity, message, file/line, and optional sim_time) onto a
+typed violations table, bound views, and findings. Pure function
+of the parsed output: no I/O, no tool calls, deterministic ids
+derived from the run id. A clean sim yields an empty table and no
+findings.
+"""
+
+TASK = "run_hdl_test"
+
+_DIAG_CAP = 240
+
+_SEVERITY = {"error": "error", "warning": "warning"}
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _location(violation):
+    """Render one file:line location string for a violation.
+
+    Args:
+        violation: v0 violation with optional file and line.
+
+    Returns:
+        Location text, or an empty string when unlocated.
+    """
+    file = violation.get("file") or ""
+    line = violation.get("line")
+    if file and line is not None:
+        return f"{file}:{line}"
+    return file or ""
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one hdl-sim parse output to a v1 ResultBundle.
+
+    Violation rows become a table dataset (rule, severity,
+    message, location) plus a bound table view; every violation
+    also becomes a finding with a capped message.
+
+    Args:
+        parsed: v0 parse mapping with ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:violations"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(violations),
+            "columns": [
+                {
+                    "id": f"{table_id}:rule",
+                    "name": "rule",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [v.get("rule", "") for v in violations],
+                },
+                {
+                    "id": f"{table_id}:severity",
+                    "name": "severity",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [v.get("severity", "") for v in violations],
+                },
+                {
+                    "id": f"{table_id}:message",
+                    "name": "message",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [_cap(v.get("message", "")) for v in violations],
+                },
+                {
+                    "id": f"{table_id}:location",
+                    "name": "location",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [_location(v) for v in violations],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:violations",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "violations",
+        }
+    ]
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": _SEVERITY.get(v.get("severity"), "info"),
+            "code": v.get("rule", "sim"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "not_applicable",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": [],
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/hdl_sim/verilator.py

@@ -0,0 +1,167 @@
+"""Verilator provider: run_hdl_test with SARIF plus lint text."""
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_hdl_test"
+_TOOL = "verilator"
+_DIAG_RE = re.compile(
+    r"^%((?:Error)|(Warning)-([A-Z0-9_]+)):\s*(.+?):(\d+):(\d+):")
+
+
+class VerilatorAdapter(ToolAdapter):
+    """run_hdl_test via verilator: lint plus sim harness verdicts.
+
+    Serves the run_hdl_test operation with tool `verilator`.
+    Lint runs `--lint-only --diagnostics-sarif`; the SARIF file is
+    the first channel, `%Error`/`%Warning` stderr the fallback
+    (xml-only is dead since 5.046 — json-only/SARIF only).
+
+    Job keys:
+        sources (required): Verilog source paths.
+        top: Top module name.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 120).
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL,
+                "modes": ["lint", "sim"]}
+
+    def preflight(self, job):
+        """Check operation, sources, and verilator presence.
+
+        Args:
+            job: Solver job with operation run_hdl_test.
+
+        Returns:
+            Checked mapping with binary, sources, timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for missing sources, missing_dependency when
+                verilator is absent (BLOCKED-needs-host).
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Verilator handles {OPERATION}, got {job.get('operation')}.")
+        sources = job.get("sources") or []
+        missing = [s for s in sources if not Path(s).is_file()]
+        if not sources or missing:
+            raise AdapterError(
+                "invalid_reference", f"Sources not found: {missing or sources}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: verilator not on PATH.")
+        timeout = job.get("timeout_s", 120)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        return {"binary": binary, "sources": list(sources),
+                "top": job.get("top"), "timeout_s": timeout}
+
+    def execute(self, job):
+        """Lint the sources with verilator under a timeout.
+
+        Args:
+            job: Solver job with operation run_hdl_test.
+
+        Returns:
+            Native output with exit_code, stderr, sarif, sources.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", ".")
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        argv = [checked["binary"], "--lint-only", "--diagnostics-sarif",
+                "--Mdir", "obj_dir", *checked["sources"]]
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True,
+                                  timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Verilator run timed out.") from exc
+        sarif = None
+        for cand in (Path(workdir) / "obj_dir").glob("*.sarif"):
+            try:
+                sarif = json.loads(cand.read_text())
+            except ValueError:
+                sarif = None
+            break
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "sarif": sarif,
+                "sources": checked["sources"]}
+
+    def parse(self, native_output):
+        """Parse SARIF results, else lint stderr diagnostics.
+
+        Args:
+            native_output: Native output with sarif/stderr.
+
+        Returns:
+            {total, violations[], source}.
+        """
+        sarif = native_output.get("sarif")
+        if isinstance(sarif, dict):
+            violations = []
+            for run in sarif.get("runs") or []:
+                for res in run.get("results") or []:
+                    locs = res.get("locations") or [{}]
+                    phys = locs[0].get("physicalLocation") or {}
+                    region = phys.get("region") or {}
+                    art = phys.get("artifactLocation") or {}
+                    violations.append({
+                        "rule": res.get("ruleId", "verilator"),
+                        "severity": ("error" if res.get("level") == "error"
+                                     else "warning"),
+                        "message": ((res.get("message") or {}).get("text")
+                                    or "Verilator diagnostic."),
+                        "file": art.get("uri", ""),
+                        "line": int(region.get("startLine", 1)),
+                    })
+            errors = [v for v in violations if v["severity"] == "error"]
+            if native_output.get("exit_code", 0) != 0 and not violations:
+                violations = [{"rule": "lint_error", "severity": "error",
+                               "message": "Verilator exited "
+                                          f"{native_output.get('exit_code')}."}]
+            return {"total": len(violations), "violations": violations,
+                    "source": "sarif"}
+        violations = []
+        for line in (native_output.get("stderr") or "").splitlines():
+            match = _DIAG_RE.match(line)
+            if match is None:
+                continue
+            kind, _warn, code, path, line_no, _col = match.groups()
+            violations.append({
+                "rule": code or ("lint_error"
+                                 if kind == "Error" else "lint_warning"),
+                "severity": "error" if kind == "Error" else "warning",
+                "message": line[:300], "file": path, "line": int(line_no)})
+        if native_output.get("exit_code", 0) != 0 and not violations:
+            violations = [{"rule": "lint_error", "severity": "error",
+                           "message": "Verilator exited "
+                                      f"{native_output.get('exit_code')}."}]
+        return {"total": len(violations), "violations": violations,
+                "source": "stderr"}

rocket_engine/adapters/http/README.md

@@ -0,0 +1,15 @@
+# HTTP JSON command transport
+
+HttpTransport.handle parses one JSON object containing project_id, operation, optional arguments, and optional request_id. It enforces an optional bound project and delegates to Engine.submit. `serve_http` wraps the same transport in a FastAPI app on uvicorn: POST a JSON envelope to `/` for an admission ack or query result, GET `/health` for a liveness probe, GET `/events` for the runtime lifecycle log as Server-Sent Events (PUSH-EVENTS; pass a runtime to `serve_http`/`create_server`/`create_app` to bind it — replay since `cursor`, then live frames with heartbeat comments). Without a bound runtime `/events` refuses loudly with `runner_unavailable` (503); polling get_events_since stays the watch path there.
+
+## Listener hardening
+
+POST `/` requires `Content-Type: application/json` (415 otherwise), refuses bodies over 1 MiB (413), accepts a missing Origin or a loopback one only (403 for foreign origins — the browser-CSRF class), and bounds concurrency at 32 in-flight requests (503 + Retry-After on overflow). Engine errors serialize with their v0 code, message, and fields at the status from the shared code table (`adapters/errors.py`, pinned to the v1 errors catalog); uncoded crashes become a generic 500 with the traceback server-side only. Every request writes one audit line (`METHOD /path -> status`) to the `rocket_engine.http` logger.
+
+## Trust boundary (ADR-006)
+
+This adapter is localhost-only with no auth, serving the same caller-blind API as every other transport. The trust boundary is the loopback interface: `serve_http`/`create_server` bind loopback hosts only (127.0.0.1 by default; any 127/8 address, `localhost`, or `::1`) and refuse any non-loopback bind with `non_loopback_bind_denied`. Startup prints a banner stating the model. Remote/multi-user access needs a separate authenticated adapter — never this one with a flag. See the [HTTP boundary decision](../../../docs/adr/006-localhost-only-http.md) and the [provision plan](../../../docs/provision-plan.md#loopback-only-http-no-remote-deploy).
+
+## Boundaries
+
+The adapter owns JSON parsing, request IDs, and project-scope checks. It does not own operation validation, state, solver selection, or verdicts. Command shapes are shared with [interfaces](../../interfaces/README.md); the parent transport map is in [adapters](../README.md).