rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/xschem/deck.py

@@ -0,0 +1,266 @@
+"""Xschem netlist-to-sim deck: one call from schematic to verdict.
+
+The solver adapter (`src/adapters/xschem/__init__.py`) netlists one
+schematic per call. This deck chains the two deck phases behind one
+call: netlist the schematic, refuse an empty (device-free) netlist
+loudly instead of fake-greening it, and optionally run the
+schematic-owned sim (`-S`) whose failures combine under the same
+verdict. Engine vocabulary/composition wiring belongs to the owning
+surface; this file only orchestrates the solver.
+"""
+
+from pathlib import Path
+
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+from . import XschemAdapter
+
+OPERATION = "run_xschem"
+
+
+def deck_elements(text):
+    """Device lines of one netlist, without comments or directives.
+
+    Args:
+        text: Raw (or normalized) netlist text.
+
+    Returns:
+        Device lines such as `V1 ...` or `X...`, in file order.
+            Comment lines (`*...`), dot directives (`.end`,
+            `.GLOBAL`), and blanks never count as devices.
+    """
+    lines = []
+    for line in (text or "").splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith(("*", ".")):
+            continue
+        lines.append(line)
+    return lines
+
+
+class XschemDeck(ToolAdapter):
+    """run_xschem as a deck: netlist, guard empty, optionally sim.
+
+    Serves the run_xschem operation with tool `xschem` in deck
+    modes (`netlist`, `sim`, `deck`). Phase one netlists the
+    schematic; a netlist with zero device lines fails loudly as
+    `empty_netlist` (an empty schematic or all symbols missing
+    never parses as clean). Phase two, only when the job sets
+    `sim`, reruns with the schematic-owned sim (`-S`) and reports
+    its failures under `sim`.
+
+    Job keys:
+        sch_file (required): Schematic file under netlist.
+        rcfile: Project rcfile path (library paths may derive
+            from the adapter-pinned XSCHEM_SHAREDIR).
+        output_name: Netlist file name (default `<stem>.spice`).
+        flat: Flat netlist (`-f`) when true.
+        sim: Run the schematic-owned sim (`-S`) when true.
+        workdir: Run directory (default ".").
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+        xschem_bin: Explicit xschem binary; PATH when None.
+
+    Caution: The deck reruns the netlister for the sim phase, so
+        a schematic whose outputs differ run to run decks
+        non-deterministically — byte-compare only the netlist
+        phase, never the sim phase.
+    """
+
+    def __init__(self, runner=None, xschem_bin=None):
+        self._runner = runner
+        self._xschem_bin = xschem_bin
+
+    def capabilities(self, target):
+        """Report the served operation, tool, and deck modes.
+
+        Args:
+            target: Target the capabilities are reported for
+                (accepted, unused — one schematic per job).
+
+        Returns:
+            Capability mapping with operations, tool, and modes.
+        """
+        return {
+            "operations": [OPERATION],
+            "tool": "xschem",
+            "modes": ["netlist", "sim", "deck"],
+        }
+
+    def _adapter(self):
+        """One solver adapter sharing this deck's runner and binary."""
+        return XschemAdapter(
+            runner=self._runner, xschem_bin=self._xschem_bin)
+
+    def netlist(self, job):
+        """Netlist one schematic and parse it to a deck verdict.
+
+        Args:
+            job: Solver job with operation run_xschem plus
+                sch_file and deck inputs (any `sim` flag is
+                ignored: this phase never simulates).
+
+        Returns:
+            Mapping with netlist_file, normalized_text, elements
+                (device lines), total, and violations.
+
+        Raises:
+            AdapterError: invalid_reference for a missing
+                schematic/rcfile, missing_dependency without
+                xschem V3, runner_unavailable with no netlist
+                output, plus the solver preflight codes.
+        """
+        adapter = self._adapter()
+        native = adapter.execute(dict(job, sim=False))
+        parsed = adapter.parse(native)
+        elements = deck_elements(native.get("normalized_text"))
+        return {
+            "netlist_file": native.get("netlist_file"),
+            "normalized_text": native.get("normalized_text"),
+            "elements": elements,
+            "total": parsed.get("total"),
+            "violations": list(parsed.get("violations") or []),
+        }
+
+    def deck(self, job):
+        """Deck one schematic from netlist to an optional sim verdict.
+
+        Args:
+            job: Solver job with operation run_xschem plus
+                sch_file and deck inputs; `sim` true adds the
+                schematic-owned sim phase.
+
+        Returns:
+            Netlist verdict (netlist_file, normalized_text,
+                elements, total, violations) plus `sim`: None
+                without the sim flag, else the sim failures as
+                {total, violations, log_file}. A device-free
+                netlist appends an `empty_netlist` error and
+                skips the sim phase.
+
+        Raises:
+            AdapterError: invalid_reference for a missing
+                schematic, missing_dependency without xschem
+                V3, runner_unavailable with no netlist output,
+                plus the solver preflight codes (netlist first,
+                sim reruns the same checks).
+        """
+        verdict = self.netlist(job)
+        if not verdict["elements"]:
+            verdict["violations"] = verdict["violations"] + [{
+                "rule": "empty_netlist",
+                "severity": "error",
+                "message": ("xschem deck netlist has no device lines: "
+                            "empty schematic or all symbols missing."),
+            }]
+            verdict["total"] = len(verdict["violations"])
+            verdict["sim"] = None
+            return verdict
+        if not job.get("sim"):
+            verdict["sim"] = None
+            return verdict
+        adapter = self._adapter()
+        sim_native = adapter.execute(dict(job, sim=True))
+        sim_parsed = adapter.parse(sim_native)
+        sim_fails = [v for v in (sim_parsed.get("violations") or [])
+                     if v.get("rule") == "xschem_sim_fail"]
+        verdict["sim"] = {
+            "total": len(sim_fails),
+            "violations": sim_fails,
+            "log_file": sim_native.get("log_file"),
+        }
+        return verdict
+
+    def preflight(self, job):
+        """Check the deck job through the solver preflight.
+
+        Args:
+            job: Solver job with operation run_xschem plus
+                sch_file and deck inputs.
+
+        Returns:
+            Checked mapping from the solver preflight.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference,
+                invalid_command, or missing_dependency, exactly as
+                the solver reports them.
+        """
+        return self._adapter().preflight(job)
+
+    def execute(self, job):
+        """Deck one schematic: netlist natively, sim natively on flag.
+
+        Args:
+            job: Solver job with operation run_xschem plus
+                sch_file and deck inputs.
+
+        Returns:
+            Native output with the netlist phase and, on the sim
+                flag with devices present, the sim phase.
+
+        Raises:
+            AdapterError: invalid_reference, missing_dependency,
+                or runner_unavailable, exactly as the solver
+                reports them.
+        """
+        net_native = self._adapter().execute(dict(job, sim=False))
+        phases = {"netlist": net_native, "sim": None}
+        if job.get("sim") and deck_elements(
+                net_native.get("normalized_text")):
+            phases["sim"] = self._adapter().execute(dict(job, sim=True))
+        return phases
+
+    def parse(self, native_output):
+        """Parse deck natives to the combined deck verdict.
+
+        Args:
+            native_output: Native output with netlist (and
+                optional sim) phases from execute.
+
+        Returns:
+            Deck verdict with elements, violations (including
+                the empty_netlist guard), and the sim sub-verdict.
+
+        Raises:
+            AdapterError: runner_unavailable when the netlist
+                phase is missing.
+        """
+        adapter = self._adapter()
+        net_native = (native_output or {}).get("netlist")
+        if net_native is None:
+            raise AdapterError(
+                "runner_unavailable", "xschem deck has no netlist phase.")
+        parsed = adapter.parse(net_native)
+        elements = deck_elements(net_native.get("normalized_text"))
+        violations = list(parsed.get("violations") or [])
+        if not elements:
+            violations = violations + [{
+                "rule": "empty_netlist",
+                "severity": "error",
+                "message": ("xschem deck netlist has no device lines: "
+                            "empty schematic or all symbols missing."),
+            }]
+        sim_native = (native_output or {}).get("sim")
+        sim = None
+        if sim_native is not None:
+            sim_parsed = adapter.parse(sim_native)
+            sim_fails = [v for v in (sim_parsed.get("violations") or [])
+                         if v.get("rule") == "xschem_sim_fail"]
+            sim = {
+                "total": len(sim_fails),
+                "violations": sim_fails,
+                "log_file": sim_native.get("log_file"),
+            }
+        return {
+            "netlist_file": net_native.get("netlist_file"),
+            "normalized_text": net_native.get("normalized_text"),
+            "elements": elements,
+            "total": (len(violations) if not elements
+                      else parsed.get("total")),
+            "violations": violations,
+            "sim": sim,
+        }

rocket_engine/clients/__init__.py

@@ -0,0 +1,5 @@
+"""Migrated v1 clients over one engine's integrated runtime."""
+
+from .runtime import RuntimeClient
+
+__all__ = ["RuntimeClient"]

rocket_engine/clients/runtime.py

@@ -0,0 +1,255 @@
+"""Shared client over one engine's integrated runtime (CLIENTS).
+
+Every transport (MCP, HTTP, IPC, stdio console, Python) serves the
+same EngineRuntime through this one client instead of inventing
+its own queue. All run control delegates to the engine's public
+deferred surface — the client never constructs a second runtime,
+never reimplements admission, and never synthesizes verdicts.
+
+Caution: The push-listener handle (`add_listener`) stays behind
+the runtime object the servers bind explicitly; the engine
+exposes no public listener accessor yet (see the API-V1-CLIENTS
+verdict carry). Watch polling and cursor recovery ride the
+public `runtime_events` surface instead.
+"""
+
+from ..project.errors import ProjectError
+
+
+class RuntimeClient:
+    """One engine's deferred runs, served to every client alike.
+
+    Args:
+        engine: Engine whose integrated runtime this client
+            serves (submit, deferred submit/pump/wait/fetch,
+            cancel, watch, survivors).
+    """
+
+    def __init__(self, engine):
+        self._engine = engine
+        self._paused = False
+
+    @property
+    def engine(self):
+        """Engine this client serves.
+
+        Returns:
+            The bound engine.
+        """
+        return self._engine
+
+    @property
+    def paused(self):
+        """Client-side capacity signal from the last refusal.
+
+        True after a deferred admission refused with admitted
+        False (retryable saturation); False again once a pump,
+        cancel, or admitted submit frees the lane.
+
+        Returns:
+            Whether the client believes admission is paused.
+        """
+        return self._paused
+
+    def submit(self, project_id, operation, arguments, request_id=None):
+        """Submit one call inline through the engine.
+
+        Args:
+            project_id: Project the call runs against.
+            operation: Cataloged operation or query name.
+            arguments: Operation arguments mapping.
+            request_id: Client envelope id; minted when omitted.
+
+        Returns:
+            Engine result for the call (ack, completion, or data).
+        """
+        command = {
+            "project_id": project_id,
+            "operation": operation,
+            "arguments": dict(arguments),
+        }
+        if request_id is not None:
+            command["request_id"] = request_id
+        return self._engine.submit(command)
+
+    def deferred_submit(self, operation, arguments, request_id=None):
+        """Admit one deferred run with a prompt acknowledgement.
+
+        Args:
+            operation: Cataloged operation name.
+            arguments: Operation arguments mapping.
+            request_id: Client envelope id; minted when omitted.
+
+        Returns:
+            Deferred handle watching the admitted run; the
+            receipt carries no verdict. A refused handle carries
+            admitted False and marks this client paused.
+        """
+        handle = self._engine.deferred_submit(
+            operation, dict(arguments or {}), request_id=request_id)
+        receipt = handle.receipt
+        if receipt.get("admitted") is False:
+            self._paused = True
+        else:
+            self._paused = False
+        return handle
+
+    def pump(self, limit=None):
+        """Dispatch queued deferred runs oldest first.
+
+        Args:
+            limit: Maximum entries to drain; the whole backlog
+                when omitted.
+
+        Returns:
+            Completions in dispatch order. A drained lane clears
+                this client's paused signal.
+        """
+        completions = self._engine.deferred_pump(limit=limit)
+        if completions:
+            self._paused = False
+        return completions
+
+    def wait_for(self, run_id, timeout=None):
+        """Block until one deferred run reaches a terminal state.
+
+        Args:
+            run_id: Deferred run id to wait for.
+            timeout: Maximum seconds to wait; waits with the run
+                when omitted.
+
+        Returns:
+            Terminal completion for the run.
+        """
+        return self._engine.deferred_wait(run_id, timeout=timeout)
+
+    def status(self, run_id):
+        """Read one deferred run's state, verdict, and operation.
+
+        Args:
+            run_id: Deferred run id to inspect.
+
+        Returns:
+            Status with run_id, operation, state, and verdict
+                once judged.
+        """
+        return self._engine.deferred_status(run_id)
+
+    def fetch(self, run_id):
+        """Fetch one deferred run's merged ack-plus-completion.
+
+        Args:
+            run_id: Deferred run id to fetch.
+
+        Returns:
+            Merged receipt-plus-completion; verdict present once
+                the run finished.
+        """
+        return self._engine.deferred_fetch(run_id)
+
+    def cancel(self, run_id, actor=None):
+        """Cancel one queued or running deferred run.
+
+        Args:
+            run_id: Deferred run id to cancel.
+            actor: Attribution for the lifecycle event; the
+                engine actor when omitted.
+
+        Returns:
+            Outcome with run_id, state, actor, and verdict when
+                judged. A freed lane clears this client's paused
+                signal.
+        """
+        outcome = self._engine.runtime_cancel(run_id, actor=actor)
+        self._paused = False
+        return outcome
+
+    def watch(self, cursor=0):
+        """Read ordered lifecycle events after a cursor.
+
+        A cursor the retained log no longer covers recovers
+        loudly: the page replays from the floor and reports
+        resynced True with the current revision instead of
+        failing the subscriber.
+
+        Args:
+            cursor: Opaque position from a previous read; 0
+                replays the retained log.
+
+        Returns:
+            Page with events oldest first, the current cursor,
+                and resynced True only after a recovery replay.
+
+        Raises:
+            ProjectError: any runtime refusal other than
+                cursor_expired — expired cursors recover,
+                never raise.
+        """
+        try:
+            page = self._engine.runtime_events(cursor)
+        except ProjectError as err:
+            if err.code != "cursor_expired":
+                raise
+            snapshot = self._engine.snapshot()
+            page = self._engine.runtime_events(0)
+            return {
+                "events": page["events"],
+                "cursor": page["cursor"],
+                "resynced": True,
+                "current_revision": snapshot["current_revision"],
+            }
+        return {
+            "events": page["events"],
+            "cursor": page["cursor"],
+            "resynced": False,
+        }
+
+    def survivors(self):
+        """Report unfinished deferred runs without executing any.
+
+        Returns:
+            Boot report with survivors, interrupted, and
+                quarantined run ids.
+        """
+        return self._engine.boot_report()
+
+    def resume(self, run_id, force=False):
+        """Resume one crash-surviving deferred run.
+
+        Args:
+            run_id: Survivor to execute now.
+            force: Required to resume a quarantined run.
+
+        Returns:
+            Resume outcome for the run.
+        """
+        return self._engine.resume_survivor(run_id, force=force)
+
+    def discard(self, run_id):
+        """Discard one crash-surviving deferred run.
+
+        Args:
+            run_id: Survivor to discard.
+
+        Returns:
+            Discard record for the run.
+        """
+        return self._engine.discard_survivor(run_id)
+
+    def resume_all(self):
+        """Resume every retryable crash survivor.
+
+        Returns:
+            Gated batch with resumed run ids, their
+                completions, and skipped entries.
+        """
+        return self._engine.resume_all_retryable()
+
+    def replay_pending(self):
+        """Resume crash-surviving RETRYABLE admissions, oldest first.
+
+        Returns:
+            Report with replayed run ids, their completions, and
+                skipped entries.
+        """
+        return self._engine.replay_pending()