rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/ops/deferred.py

@@ -0,0 +1,279 @@
+"""Wave-3 deferred runtime seam (EngineRuntime integration).
+
+Engine owns one EngineRuntime bound to the solver lane: deferred
+submits acknowledge promptly with a run id and no verdict, the
+pump executes through the ledger-admitting runner, and the
+terminal completion merges back with merge_ack_completion. The
+synchronous submit path is untouched — deferred runs correlate
+with ledger admissions through the shared request id.
+"""
+
+from ..execution.apig.submit import merge_ack_completion
+from ..interfaces.yaml_dump import dump_yaml_text
+from ..project.errors import ProjectError
+
+
+class _DeferredMixin:
+    """Deferred prompt-ack runtime surface (Wave-3 EngineRuntime)."""
+
+    def _deferred_runner(
+            self, operation, arguments, snapshot_id, request_id,
+            run_id):
+        """Execute one deferred run through ledger admission.
+
+        Admission gates exactly like a synchronous submit
+        (targets, request knobs, confinement, budget, verdict
+        gates, block scope); the ledger ack run id executes while
+        the runtime tracks its own run id. Replay hits return the
+        stored completion without re-executing.
+
+        Args:
+            operation: Cataloged solver operation name.
+            arguments: Operation arguments mapping.
+            snapshot_id: Evidence snapshot the run pins.
+            request_id: Client envelope id.
+            run_id: Runtime run id tracking this run.
+
+        Returns:
+            Terminal completion for the run.
+        """
+        from .gates import check_submit_gates
+
+        args = dict(arguments or {})
+        args = self._apply_targets(operation, args)
+        args = self._apply_run_request(args)
+        if operation == "run_spice":
+            args = self.confine_spice_arguments(
+                args, self._project_dir)
+        from .runs import refuse_smuggled_budget
+
+        refuse_smuggled_budget(args)
+        check_submit_gates(operation, args, self._project)
+        scope_request = self._admit_block_scope(operation, args)
+        command_text = dump_yaml_text(
+            {"operation": operation, "arguments": args})
+        ack = self._pool.submit_request(
+            command_text, str(request_id),
+            expected_revision=args.get("expected_revision"),
+        )
+        self._deferred.apply_edit()
+        ledger_id = ack["run_id"]
+        stored = self._stored_completion(ledger_id)
+        if stored is not None:
+            self._pool.discard(ledger_id)
+            return {
+                "run_id": ledger_id, "state": stored["state"],
+                "verdict": stored.get("verdict"),
+                "operation": stored.get("operation"),
+            }
+        self._run_jobs.setdefault(
+            ledger_id,
+            {
+                "operation": operation,
+                "arguments": args,
+                "snapshot_id": ack["snapshot_id"],
+                "request_id": str(request_id),
+            },
+        )
+        if scope_request is not None:
+            from ..execution.block_runs_scope import (
+                build_scope_record,
+            )
+
+            pending = self._run_jobs[ledger_id]
+            if "block_scope" not in pending:
+                pending["block_scope"] = build_scope_record(
+                    run_id=ledger_id,
+                    revision=self._project.snapshot()[
+                        "current_revision"],
+                    block_id=scope_request["block_id"],
+                    deck=args.get("deck"),
+                    closure=scope_request["closure"],
+                )
+        if not self._execution.known(ledger_id):
+            self._execution.dispatch(
+                operation, {"cell": args.get("cell")},
+                ack["snapshot_id"], run_id=ledger_id,
+            )
+        try:
+            completion = self._pool_execute(
+                operation, args, ack["snapshot_id"],
+                str(request_id), ledger_id)
+        finally:
+            self._pool.discard(ledger_id)
+        self._maybe_record_evidence(operation, completion, args)
+        return completion
+
+    def deferred_submit(self, operation, arguments, request_id=None):
+        """Admit one deferred run with a prompt acknowledgement.
+
+        The receipt carries the run id with no verdict; pump (or
+        auto-dispatch) executes, then merge the terminal
+        completion back with merge_ack_completion.
+
+        Args:
+            operation: Cataloged solver operation name.
+            arguments: Operation arguments mapping.
+            request_id: Client envelope id; minted when omitted.
+
+        Returns:
+            DeferredHandle watching the admitted run.
+
+        Raises:
+            ProjectError: unsupported_operation for an unknown
+                name; the runtime refusal code otherwise.
+        """
+        from ..execution.errors import ExecutionError
+        from ..interfaces.vocabulary import OPERATIONS
+
+        if operation not in OPERATIONS:
+            raise ProjectError(
+                "unsupported_operation",
+                f"Unsupported operation: {operation}.",
+            )
+        import uuid as _uuid
+
+        try:
+            handle = self._deferred.submit(
+                operation, dict(arguments or {}),
+                request_id=str(request_id or _uuid.uuid4().hex),
+            )
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+        self._deferred_receipts[handle.run_id] = dict(
+            handle.receipt)
+        return handle
+
+    def deferred_pump(self, limit=None):
+        """Dispatch deferred runs oldest first through the runner.
+
+        Args:
+            limit: Maximum entries to drain; the whole backlog
+                when omitted.
+
+        Returns:
+            Completions in dispatch order.
+        """
+        return self._deferred.pump(limit=limit)
+
+    def deferred_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.
+        """
+        from ..execution.errors import ExecutionError
+
+        try:
+            return self._deferred.status(run_id)
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+
+    def deferred_wait(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.
+        """
+        from ..execution.errors import ExecutionError
+
+        try:
+            return self._deferred.wait_for(
+                run_id, timeout=timeout)
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+
+    def runtime_events(self, cursor=0):
+        """Read ordered deferred lifecycle events after a cursor.
+
+        Args:
+            cursor: Opaque position from a previous read; 0
+                replays the retained log.
+
+        Returns:
+            Events appended after the cursor, oldest first,
+                plus the current cursor.
+        """
+        from ..execution.errors import ExecutionError
+
+        try:
+            return self._deferred.watch(cursor)
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+
+    def runtime_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.
+
+        Returns:
+            Outcome with run_id, state, actor, and verdict
+                when judged.
+        """
+        from ..execution.errors import ExecutionError
+
+        try:
+            return self._deferred.cancel(
+                run_id,
+                actor=actor if actor is not None else self._actor,
+            )
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+
+    def replay_pending(self):
+        """Resume crash-surviving RETRYABLE admissions, oldest first.
+
+        Explicit-call compat over the gated batch: same survivor
+        set as the boot report, but only RETRYABLE runs execute —
+        ambiguous and poison survivors are skipped loudly in the
+        report instead of re-running.
+
+        Returns:
+            Report with replayed run ids (the resumed set, seq
+                order), their completions, and skipped entries.
+        """
+        batch = self._replay.resume_all_retryable()
+        return {
+            "replayed": batch["resumed"],
+            "completions": batch["completions"],
+            "skipped": batch["skipped"],
+        }
+
+    def deferred_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.
+
+        Raises:
+            ProjectError: unknown_run for an untracked id.
+        """
+        from ..execution.errors import ExecutionError
+
+        try:
+            receipt = self._deferred_receipts[run_id]
+        except (KeyError, AttributeError):
+            raise ProjectError(
+                "unknown_run", f"Unknown run: {run_id}.") from None
+        try:
+            completion = self._deferred.wait_for(run_id, timeout=0)
+        except TimeoutError:
+            return dict(receipt)
+        except ExecutionError as exc:
+            raise ProjectError(exc.code, str(exc)) from exc
+        return merge_ack_completion(receipt, completion)

rocket_engine/ops/editors.py

@@ -0,0 +1,404 @@
+"""Wave-3 editor seam: shared admission helpers plus Engine dispatch.
+
+Service-side endpoint methods stay thin: every Wave-3 mutation
+rides the wire envelope through editor_mutation, every computed
+read serves through editor_read. Receipts carry I28 closure pins
+via pin_receipt. The Engine-side _EditorMixin (query dispatch)
+lives here too, so both sides of the seam share one module.
+"""
+
+from ..interfaces.errors import ContractError
+from ..interfaces.refs import pin_closure
+from ..project.errors import ProjectError
+
+
+def editor_value_error(func):
+    """Run editor logic, mapping value errors to ProjectError.
+
+    Args:
+        func: Zero-argument callable running the domain op.
+
+    Returns:
+        Whatever the domain op returns.
+
+    Raises:
+        ProjectError: invalid_command (or the carried code).
+    """
+    try:
+        return func()
+    except ValueError as exc:
+        raise ProjectError(
+            getattr(exc, "code", "invalid_command"), str(exc)
+        ) from exc
+
+
+def pin_receipt(service, receipt):
+    """Attach the I28 closure pin to one editor receipt.
+
+    Entity ids carried by the receipt pin their live revisions;
+    unresolvable names are skipped, never guessed. Prior partial
+    pins (template, profile) are preserved and folded in.
+
+    Args:
+        service: ProjectService handle to read through.
+        receipt: Editor receipt mapping (mutated in place).
+
+    Returns:
+        The same receipt with an i28 closure pin.
+    """
+    from ..project.edit import cas as _cas
+
+    revisions = {}
+    prior = {}
+    if isinstance(receipt, dict):
+        prior = receipt.get("i28") or {}
+        for key in (
+            "entity", "sheet", "instance", "binding",
+            "symbol", "cell", "ip", "testbench", "shape",
+        ):
+            candidate = receipt.get(key)
+            if not isinstance(candidate, str):
+                continue
+            try:
+                revisions[candidate] = _cas.read_entity_revision(
+                    service, candidate)
+            except Exception:  # noqa: BLE001 — names skip
+                continue
+    receipt["i28"] = pin_closure(
+        service.snapshot()["current_revision"], entities=revisions,
+        template=prior.get("template"),
+        profile=prior.get("profile"))
+    return receipt
+
+
+def editor_mutation(service, operation, request_id, command_text,
+                    expected_revision, run, describe):
+    """Admit one Wave-3 editor op through the wire envelope.
+
+    Inner envelopes derive from the outer request id, so a
+    retried envelope replays the verbs that already landed
+    instead of minting duplicates.
+
+    Args:
+        service: ProjectService handle to write through.
+        operation: Editor operation name for the event data.
+        request_id: Client envelope id for idempotent replay.
+        command_text: YAML command text for identity comparison.
+        expected_revision: Revision the writer read.
+        run: Callable (store, inner_id, inner_text, live)
+            returning the domain receipt.
+        describe: Callable (receipt) -> diff summary text.
+
+    Returns:
+        Mutation mapping with the pinned receipt, revision
+        transition, actor, events, cursor, and request id.
+
+    Raises:
+        ProjectError: request_conflict, revision_conflict,
+            or the domain refusal code.
+    """
+    def _run(store):
+        return pin_receipt(service, editor_value_error(
+            lambda: run(
+                store, f"{request_id}:{operation}",
+                f"{command_text}\n#inner {operation}",
+                service.snapshot()["current_revision"])))
+    return service._wire_mutation(
+        operation, request_id, command_text,
+        expected_revision, _run, describe)
+
+
+def editor_read(service, operation, func):
+    """Serve one Wave-3 computed read with revision and I28.
+
+    Args:
+        service: ProjectService handle to read through.
+        operation: Read name for the entity-store seam tag.
+        func: Callable (store) returning the result mapping.
+
+    Returns:
+        Result mapping plus head revision and I28 pin.
+
+    Raises:
+        ProjectError: The domain refusal code.
+    """
+    store = service._entity_store(f"read:{operation}")
+    try:
+        result = func(store)
+    except ContractError as exc:
+        raise ProjectError(exc.code, str(exc)) from exc
+    return {
+        **result,
+        "current_revision": service.snapshot()["current_revision"],
+        "i28": pin_closure(service.snapshot()["current_revision"]),
+    }
+
+
+#: Wave-3 computed reads served through ProjectService verbs.
+_COMPUTED_READS = frozenset({
+    "read_entity_revision", "connection_graph", "net_occurrences",
+    "xprobe", "resolve_pin", "plot_export", "erc_check",
+    "write_netlist", "update_netlist", "check_capability",
+    "describe_testbench",
+})
+
+
+class _EditorMixin:
+    """Wave-3 editor/testbench query dispatch (Engine side)."""
+
+    def _query_editor(self, name, arguments):
+        """Serve one Wave-3 editor/testbench read query.
+
+        Generic entity reads ride the component seams; computed
+        reports delegate to the matching ProjectService verb.
+
+        Args:
+            name: Wave-3 read query name.
+            arguments: Query arguments mapping.
+
+        Returns:
+            Read mapping with head revision and I28 pin.
+
+        Raises:
+            ProjectError: invalid_command for missing arguments
+                or the domain refusal code.
+        """
+        project = self._project
+        if name == "read_entity_revision":
+            if "entity" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "read_entity_revision needs an entity.",
+                )
+            return project.entity_revision(arguments["entity"])
+        if name in ("connection_graph", "net_occurrences"):
+            return project.graph_report(
+                sheet=arguments.get("sheet"),
+                net=arguments.get("net"),
+                net_pins=arguments.get("net_pins"))
+        if name in ("xprobe", "resolve_pin"):
+            for key in ("instance", "pin"):
+                if key not in arguments:
+                    raise ProjectError(
+                        "invalid_command",
+                        f"{name} needs {key}.",
+                    )
+            return project.probe_report(
+                arguments["instance"], arguments["pin"],
+                net_pins=arguments.get("net_pins"))
+        if name == "plot_export":
+            return project.plot_report(
+                format=arguments.get("format", "svg"),
+                sheet=arguments.get("sheet"))
+        if name == "erc_check":
+            return project.erc_report(
+                severities=arguments.get("severities"),
+                pin_conflict=arguments.get("pin_conflict"),
+                net_pins=arguments.get("net_pins"))
+        if name in ("write_netlist", "update_netlist"):
+            if "language" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    f"{name} needs a language.",
+                )
+            return project.netlist_report(
+                arguments["language"],
+                sheet=arguments.get("sheet"),
+                title=arguments.get("title", "top"),
+                net_pins=arguments.get("net_pins"),
+                prior_text=arguments.get("prior_text"),
+                adopted=arguments.get("adopted", False))
+        if name == "check_capability":
+            for key in ("profile", "operation"):
+                if key not in arguments:
+                    raise ProjectError(
+                        "invalid_command",
+                        f"check_capability needs {key}.",
+                    )
+            return project.capability_report(
+                arguments["profile"], arguments["operation"],
+                bindings=arguments.get("bindings"))
+        if name == "describe_testbench":
+            if "testbench" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "describe_testbench needs a testbench.",
+                )
+            return project.testbench_report(
+                arguments["testbench"])
+        return self._query_entities(name, arguments)
+
+    def _query_entities(self, name, arguments):
+        """Serve Wave-3 reads through the component seams.
+
+        Args:
+            name: Wave-3 entity read query name.
+            arguments: Query arguments mapping.
+
+        Returns:
+            Entity data with head revision and I28 pin.
+
+        Raises:
+            ProjectError: invalid_command for missing arguments
+                or the seam refusal code.
+        """
+        from ..interfaces.refs import pin_closure as _pin
+
+        project = self._project
+        head = project.snapshot()["current_revision"]
+
+        def _wrap(payload):
+            """Attach head revision and I28 pin to one payload.
+
+            Args:
+                payload: Read payload mapping.
+
+            Returns:
+                Payload with current_revision and i28 pin.
+            """
+            return {
+                **payload, "current_revision": head,
+                "i28": _pin(head),
+            }
+
+        if name == "list_sheets":
+            return _wrap(project.entities_with("Sheet"))
+        if name == "get_sheet":
+            if "entity" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "get_sheet needs an entity.",
+                )
+            return _wrap(project.get_component(
+                arguments["entity"], "Sheet"))
+        if name == "get_instance":
+            if "entity" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "get_instance needs an entity.",
+                )
+            return _wrap(project.get_component(
+                arguments["entity"], "Instance"))
+        if name == "instances_on_sheet":
+            if "sheet" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "instances_on_sheet needs a sheet.",
+                )
+            sheet = arguments["sheet"]
+            found = []
+            for entity in project.entities_with(
+                    "Instance")["entities"]:
+                data = project.get_component(
+                    entity, "Instance")["data"]
+                if isinstance(data, dict) and data.get(
+                        "sheet") == sheet:
+                    found.append(entity)
+            return _wrap({"sheet": sheet, "instances": found})
+        if name == "list_symbols":
+            return _wrap(project.entities_with("Symbol"))
+        if name == "get_symbol":
+            if "entity" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "get_symbol needs an entity.",
+                )
+            return _wrap(project.get_component(
+                arguments["entity"], "Symbol"))
+        if name == "get_cell":
+            if "entity" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "get_cell needs an entity.",
+                )
+            return _wrap(project.get_component(
+                arguments["entity"], "Cell"))
+        if name == "list_layers":
+            try:
+                doc = project.read_doc("layers/bindings.yaml")
+            except ProjectError as exc:
+                if exc.code == "unknown_document":
+                    raise ProjectError(
+                        "invalid_command",
+                        "No bindings saved yet: run bind_layers.",
+                    ) from exc
+                raise
+            return _wrap({"bindings_path": doc["path"],
+                          "content": doc["content"]})
+        if name == "list_testbenches":
+            return _wrap(project.entities_with("Testbench"))
+        if name == "ip_search":
+            if "pdk" not in arguments:
+                raise ProjectError(
+                    "invalid_command",
+                    "ip_search needs a pdk.",
+                )
+            wanted = arguments.get("name_filter")
+            found = []
+            for entity in project.entities_with(
+                    "IpBlock")["entities"]:
+                data = project.get_component(
+                    entity, "IpBlock")["data"]
+                if not isinstance(data, dict):
+                    continue
+                if data.get("pdk") != arguments["pdk"]:
+                    continue
+                if wanted and wanted not in data.get("name", ""):
+                    continue
+                item = dict(data)
+                item["id"] = entity
+                found.append(item)
+            found.sort(key=lambda item: item.get("version", ""))
+            return _wrap({"pdk": arguments["pdk"],
+                          "blocks": found})
+        if name == "ip_get":
+            for key in ("pdk", "name"):
+                if key not in arguments:
+                    raise ProjectError(
+                        "invalid_command",
+                        f"ip_get needs {key}.",
+                    )
+            return _wrap(self._select_ip(
+                arguments["pdk"], arguments["name"],
+                arguments.get("version")))
+        raise ProjectError(
+            "unsupported_operation", f"Operation not wired yet: {name}.")
+
+    def _select_ip(self, pdk, name, version):
+        """Select one registered IP block, latest when unpinned.
+
+        Args:
+            pdk: Owning PDK id (shared blocks qualify too).
+            name: Block name within the registry.
+            version: Revision label, or None for the greatest.
+
+        Returns:
+            Full block mapping with id.
+
+        Raises:
+            ProjectError: unknown_ip when no block matches.
+        """
+        project = self._project
+        candidates = []
+        for entity in project.entities_with("IpBlock")["entities"]:
+            data = project.get_component(entity, "IpBlock")["data"]
+            if not isinstance(data, dict):
+                continue
+            if data.get("name") != name:
+                continue
+            if data.get("pdk") != pdk and data.get(
+                    "scope") != "shared":
+                continue
+            item = dict(data)
+            item["id"] = entity
+            candidates.append(item)
+        if version is not None:
+            for item in candidates:
+                if item.get("version") == version:
+                    return item
+        elif candidates:
+            return sorted(
+                candidates, key=lambda item: item.get(
+                    "version", ""))[-1]
+        raise ProjectError(
+            "unknown_ip", f"No such IP block: {pdk}/{name}.")