rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/ops/evidence.py

@@ -0,0 +1,194 @@
+"""Run evidence trail: confinement + per-run evidence files.
+
+Pure helpers behind the Engine evidence seam (TRANSPORT-PARITY):
+sources resolve inside the project, the engine chooses the workdir,
+and every transport leaves the identical evidence file. The Engine
+keeps thin wrappers so the MCP server's ``Engine.confine_spice_arguments``
+seam and the submit/run call sites do not move.
+"""
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..adapters.errors import AdapterError
+
+
+def confine_spice_arguments(arguments, project_dir):
+    """Resolve run_spice sources inside the project; fix the workdir.
+
+    The engine-side confinement every transport shares
+    (TRANSPORT-PARITY): sources resolve inside the project dir,
+    a caller workdir is refused, and the workdir is the
+    results/engine-runs folder the evidence trail records
+    into. Unbound engines (no project dir) pass arguments
+    through untouched.
+
+    Args:
+        arguments: Submitted run_spice arguments.
+        project_dir: Project folder sources resolve inside, or
+            None for an unbound engine.
+
+    Returns:
+        Arguments with absolute confined sources and the
+            engine-chosen workdir (unchanged when unbound).
+
+    Raises:
+        AdapterError: invalid_reference for a source outside
+            the project, invalid_command for a caller workdir.
+    """
+    if project_dir is None:
+        return arguments
+    root = Path(project_dir).resolve()
+    confined = dict(arguments)
+    workdir = root / "results" / "engine-runs"
+    sources = confined.get("sources")
+    if isinstance(sources, list):
+        resolved = []
+        for source in sources:
+            path = (root / str(source)).resolve()
+            if not path.is_relative_to(root):
+                raise AdapterError(
+                    "invalid_reference",
+                    f"Source outside the project: {source}.",
+                )
+            resolved.append(str(path))
+        confined["sources"] = resolved
+    if "workdir" in confined and confined["workdir"] != str(workdir):
+        raise AdapterError(
+            "invalid_command",
+            "workdir is chosen by the engine, not the caller.",
+        )
+    workdir.mkdir(parents=True, exist_ok=True)
+    confined["workdir"] = str(workdir)
+    return confined
+
+
+def evidence_source_state(root):
+    """Probe (short commit, dirty) of the project tree.
+
+    Twin of the MCP server's source probe (kept local so the
+    composition root never imports an adapter): git metadata
+    when readable, (None, None) otherwise.
+
+    Args:
+        root: Project folder to probe.
+
+    Returns:
+        (commit, dirty) pair, (None, None) outside git.
+    """
+    git = ["git", "-C", str(root)]
+    head = subprocess.run(
+        [*git, "rev-parse", "--short", "HEAD"],
+        capture_output=True, text=True,
+    )
+    if head.returncode != 0:
+        return None, None
+    status = subprocess.run(
+        [*git, "status", "--porcelain", "--",
+         "design", "tests", "constraints.yaml"],
+        capture_output=True, text=True,
+    )
+    return head.stdout.strip(), bool(status.stdout.strip())
+
+
+def record_run_evidence(outcome, arguments, project_dir, log_text):
+    """Persist one finished run under results/engine-runs.
+
+    The same record shape the MCP server writes, recorded by
+    the engine itself so every transport leaves the identical
+    evidence file (TRANSPORT-PARITY): IDE buttons and agent
+    calls share one evidence trail whoever submitted.
+
+    Args:
+        outcome: Completion mapping with run_id, operation,
+            and verdict.
+        arguments: Submitted arguments (for the run's source
+            list).
+        project_dir: Project folder, or None for an unbound
+            engine (no file is written).
+        log_text: Callable taking a run_id and returning the
+            run's log text.
+
+    Returns:
+        Evidence file path string, or None when the engine is
+        unbound (no project dir anywhere).
+    """
+    if project_dir is None:
+        return None
+    folder = Path(project_dir).resolve() / "results" / "engine-runs"
+    folder.mkdir(parents=True, exist_ok=True)
+    commit, dirty = evidence_source_state(Path(project_dir).resolve())
+    sources = []
+    for source in arguments.get("sources") or []:
+        path = Path(str(source))
+        if path.is_absolute():
+            try:
+                sources.append(str(path.relative_to(
+                    Path(project_dir).resolve())))
+                continue
+            except ValueError:
+                pass
+        sources.append(str(source))
+    record = {
+        "producer": "rocket-engine",
+        "run_id": outcome["run_id"],
+        "operation": outcome["operation"],
+        "verdict": outcome["verdict"],
+        "finished_at": datetime.now(timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%SZ"),
+        "source_commit": commit,
+        "source_dirty": dirty,
+        "sources": sources,
+        "log": log_text(outcome["run_id"]),
+    }
+    path = folder / f"{outcome['run_id']}.json"
+    path.write_text(json.dumps(record, indent=2), encoding="utf-8")
+    return str(path)
+
+
+def maybe_record_evidence(project_dir, run_jobs, log_text,
+                           operation, completion, arguments):
+    """Record one completion when the engine is project-bound.
+
+    No-op for unbound engines, non-completions, and
+    verdict-less payloads (acks, batch mappings, queries).
+    run_job fetches resolve sources from the admitted
+    arguments, never the fetch envelope.
+
+    Args:
+        project_dir: Engine project folder, or None when
+            unbound.
+        run_jobs: Admitted run-job records by run_id.
+        log_text: Callable taking a run_id and returning the
+            run's log text.
+        operation: Operation hint when the completion omits it.
+        completion: Completion mapping, batch mapping, or ack.
+        arguments: Submitted arguments for the source list.
+
+    Returns:
+        Evidence file path string, or None when skipped.
+    """
+    if project_dir is None:
+        return None
+    if not isinstance(completion, dict):
+        return None
+    run_id = completion.get("run_id")
+    verdict = completion.get("verdict")
+    if run_id is None or verdict is None:
+        return None
+    pending = run_jobs.get(run_id, {})
+    sources = pending.get("arguments", arguments)
+    if not isinstance(sources, dict):
+        sources = arguments
+    return record_run_evidence(
+        {
+            "run_id": run_id,
+            "operation": completion.get("operation", operation),
+            "verdict": verdict,
+        },
+        sources,
+        project_dir,
+        log_text,
+    )

rocket_engine/ops/gates.py

@@ -0,0 +1,262 @@
+"""Engine ops mixin: Solver selection, target/constraint admission and block scope."""
+
+from ..execution.block_runs_scope import (BlockScopeError, check_operation_scope, parse_target, resolve_block, snapshot_closure)
+from ..interfaces.runparams import RunParamsError, validate_run_request
+from ..project.errors import ProjectError
+
+
+class _GateMixin:
+    """Solver selection, target/constraint admission and block scope."""
+
+    def _select_solver(self, name, arguments):
+        solvers = self._solvers.get(name) or {}
+        if not solvers:
+            raise ProjectError(
+                "unsupported_operation", f"No solver registered: {name}."
+            )
+        hint = (arguments.get("deck") or {}).get("tool")
+        if hint is None:
+            return next(iter(solvers.values()))
+        try:
+            return solvers[hint]
+        except KeyError:
+            raise ProjectError(
+                "unsupported_operation",
+                f"No {name} solver for deck tool: {hint}.",
+            ) from None
+
+    def _apply_targets(self, name, arguments):
+        """Fill run_spice metric targets from project constraints.
+
+        Caller-supplied min/max are refused (invalid_command):
+        the agent must not grade its own homework. Metrics
+        without a constraint entry fail loudly, listing the
+        constrained ones.
+        """
+        if name != "run_spice" or self._constraints is None:
+            return arguments
+        measurements = arguments.get("measurements")
+        if not isinstance(measurements, list):
+            return arguments  # the adapter's preflight reports the shape error
+        filled = []
+        control = []
+        for item in measurements:
+            if not isinstance(item, dict):
+                filled.append(item)
+                continue
+            metric = item.get("name")
+            if "min" in item or "max" in item:
+                raise ProjectError(
+                    "invalid_command",
+                    "Targets come from the project's constraints, not the call: "
+                    f"remove min/max from {metric!r}.",
+                )
+            target = self._constraints.get(metric)
+            if target is None:
+                raise ProjectError(
+                    "invalid_command",
+                    f"No target for {metric!r} in the project's constraints; "
+                    f"constrained metrics: {sorted(self._constraints)}.",
+                )
+            bounds = {key: target[key] for key in ("min", "max") if target.get(key) is not None}
+            unit = item.get("unit") or target.get("unit", "")
+            item = {**item, **bounds, "unit": unit}
+            # How a metric is measured is part of the target: a caller formula could read anything.
+            if target.get("expr") is not None:
+                if item.get("expr") not in (None, "", target["expr"]):
+                    raise ProjectError(
+                        "invalid_command",
+                        f"How {metric!r} is measured comes from the project's constraints; "
+                        "omit expr.",
+                    )
+                item["expr"] = target["expr"]
+                for line in target.get("control") or []:
+                    if line not in control:
+                        control.append(line)
+            filled.append(item)
+        updated = {**arguments, "measurements": filled}
+        if control:
+            updated["analyses"] = list(arguments.get("analyses") or []) + control
+        return updated
+
+    def _apply_run_request(self, arguments):
+        """Validate and freeze the explicit run.request knobs (RUN-PARAMS).
+
+        Every submit carries its knobs explicitly: a missing
+        `request` freezes to all defaults, a partial one fills
+        defaults, and unknown fields fail loudly — never
+        ignored. All callers (IDE, MCP, console) share this one
+        path, so the shape is identical whoever submits.
+
+        Args:
+            arguments: Submitted arguments, maybe with `request`.
+
+        Returns:
+            Arguments with `request` normalized to every knob.
+
+        Raises:
+            ProjectError: unknown_run_param for an unknown
+                field, invalid_run_param for a mistyped knob,
+                invalid_run_request for a non-mapping
+                `request`.
+        """
+        try:
+            normalized = validate_run_request(arguments.get("request"))
+        except RunParamsError as exc:
+            raise ProjectError(exc.code, str(exc), fields=exc.fields) from exc
+        return {**arguments, "request": normalized}
+
+    def _admit_block_scope(self, name, arguments):
+        """Validate a block run target and snapshot its closure.
+
+        Arguments without a target run at project scope and skip
+        this path untouched; block targets resolve their entity
+        and pin the component closure the verdict later cites.
+
+        Args:
+            name: Cataloged operation about to run.
+            arguments: Operation arguments (target rides here).
+
+        Returns:
+            None for project runs, else the admitted scope with
+                block_id and closure keys (the run_id-bound record
+                is built once the ack id exists).
+
+        Raises:
+            ProjectError: unknown_block for a block target naming
+                no block, invalid_target for a malformed target,
+                unsupported_scope for a block target on a verb
+                serving no block runs yet.
+        """
+        if "target" not in arguments:
+            return None
+        target = arguments["target"]
+        if (
+            isinstance(target, dict)
+            and target.get("scope", "project") == "project"
+        ):
+            # Project scope serves every operation and carries no
+            # block: established callers (scenario harness, adapter
+            # tests) address cells at project scope, so pass those
+            # targets through untouched — only block scope engages.
+            return None
+        try:
+            parsed = parse_target(target)
+            check_operation_scope(name, parsed["scope"])
+            if parsed["scope"] != "block":
+                return None
+            block = resolve_block(parsed["id"], self._blocks)
+            closure = snapshot_closure(block)
+        except BlockScopeError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+        return {"block_id": parsed["id"], "closure": closure}
+
+
+#: (operation, deck tool) -> prerequisite operations that must each
+#: hold at least one PASS verdict in this project. Declared by engine
+#: maintainers here — never by caller arguments. Hard deps are
+#: structural (LVS after extraction) and never forceable.
+HARD_DEPS = {
+    ("run_lvs", "netgen"): ("run_extraction",),
+    ("run_post_layout", "ngspice"): ("run_spice",),
+    ("run_timing", "opensta"): ("run_synth",),
+    ("run_digital_flow", "librelane"): ("run_syntax",),
+    ("run_formal", "sby"): ("run_synth",),
+}
+
+#: operation -> gate operations whose latest verdict must be PASS.
+#: `force=True` on the command bypasses these (and only these).
+VERDICT_GATES = {
+    "run_post_layout": ("run_spice",),
+    "run_timing": ("run_synth",),
+    "run_formal": ("run_synth",),
+}
+
+_PASS = "PASS"
+
+_COMPLETION_EVENTS = ("run_completed", "run_failed")
+
+
+def hard_dependencies(operation, deck_tool=None, caller_depends_on=None):
+    """Prerequisite operations for one solver lane.
+
+    Args:
+        operation: Solver operation about to be admitted.
+        deck_tool: Deck tool qualifier, or None for any deck.
+        caller_depends_on: Accepted and ignored — callers never
+            shape the gate table.
+
+    Returns:
+        Prerequisite operation names (possibly empty).
+    """
+    return HARD_DEPS.get((operation, deck_tool), ()) or HARD_DEPS.get(
+        (operation, None), ()
+    )
+
+
+def _completions(project):
+    """(seq, operation, status) triples from the durable ledger."""
+    try:
+        events = project.events_since(0)
+    except Exception:
+        return []
+    out = []
+    for event in events or []:
+        if event.get("event") not in _COMPLETION_EVENTS:
+            continue
+        data = event.get("data") or {}
+        operation = data.get("operation")
+        verdict = data.get("verdict") or {}
+        if operation is None:
+            continue
+        out.append((event.get("seq", 0), operation, verdict.get("status")))
+    return out
+
+
+def check_submit_gates(operation, arguments, project, force=False):
+    """Refuse an illegal solver sequence before admission.
+
+    Args:
+        operation: Solver operation about to be admitted.
+        arguments: Submit arguments (deck tool read from
+            `deck.tool` when it is a mapping).
+        project: Project port with `events_since(cursor)`.
+        force: Bypass verdict gates only; hard deps still refuse.
+
+    Returns:
+        None when every gate holds.
+
+    Raises:
+        ProjectError: unmet_dependency naming the unmet gate —
+            for an unmet hard dep (never forceable) or a
+            non-PASS latest verdict (forceable).
+    """
+    deck = (arguments or {}).get("deck")
+    deck_tool = deck.get("tool") if isinstance(deck, dict) else None
+    completions = _completions(project)
+
+    for prereq in hard_dependencies(operation, deck_tool):
+        if any(op == prereq and status == _PASS for _, op, status in completions):
+            continue
+        raise ProjectError(
+            "unmet_dependency",
+            f"{operation} needs {prereq} PASS before dispatch "
+            f"(gate: {prereq}).",
+            fields=[{"gate": prereq}],
+        )
+
+    if force:
+        return None
+    latest = {}
+    for seq, op, status in completions:
+        if seq >= latest.get(op, (-1, None))[0]:
+            latest[op] = (seq, status)
+    for gate in VERDICT_GATES.get(operation, ()):
+        if latest.get(gate, (None, None))[1] != _PASS:
+            raise ProjectError(
+                "unmet_dependency",
+                f"{operation} needs latest {gate} PASS before dispatch "
+                f"(gate: {gate}); resubmit with force to bypass.",
+                fields=[{"gate": gate}],
+            )
+    return None

rocket_engine/ops/ports.py

@@ -0,0 +1,76 @@
+"""Store port seam: protocols plus the default concrete bindings.
+
+DECOMP-CORE moves the four project stores behind ports: service
+and engine code binds stores through this module, never by
+importing ``stores`` ad hoc. Protocols declare the seam each
+store serves; ``default_ports`` documents the concrete binding
+the engine ships. Behavior is byte-identical to the direct
+store imports — the seam exists so the next slice can inject
+fakes without touching call sites.
+"""
+
+from typing import Protocol
+
+from ..stores import ecs
+from ..stores import layers
+from ..stores import settings
+from ..stores import wireplace
+
+
+class EntityPort(Protocol):
+    """Entity-store seam the project ledger writes through."""
+
+    def validate_component_name(self, component):
+        """Validate one component name, raising on misuse.
+
+        Args:
+            component: Component name to validate.
+        """
+
+
+class SettingsPort(Protocol):
+    """Settings-store seam the project service persists through."""
+
+    def validate_kind(self, kind):
+        """Validate one settings kind, raising on misuse.
+
+        Args:
+            kind: Settings kind to validate.
+        """
+
+
+class WirePort(Protocol):
+    """Wireplace seam for wire/junction admission."""
+
+    def validate_wire(self, wire):
+        """Validate one wire payload, raising on misuse.
+
+        Args:
+            wire: Wire payload to validate.
+        """
+
+
+class LayerPort(Protocol):
+    """Layer-store seam for stackup and preset serving."""
+
+    def stackup(self, pdk_id):
+        """Return the stackup rows for one PDK id.
+
+        Args:
+            pdk_id: PDK id to serve the stackup for.
+        """
+
+
+def default_ports():
+    """Return the concrete store bindings the engine ships.
+
+    Returns:
+        Mapping of port name to the concrete store module
+            serving it (ecs, settings, wireplace, layers).
+    """
+    return {
+        "ecs": ecs,
+        "settings": settings,
+        "wireplace": wireplace,
+        "layers": layers,
+    }