rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/execution/console/apply_session.py

@@ -0,0 +1,318 @@
+"""Approval-bound console cells on the atomic apply-context.
+
+CONSOLE-SESSION-MIGRATE (ADR-016 follow-up): the old in-memory
+`ConsoleSession` (approved code plus history cursor, environment
+digest, and revision binding, with reset killing every outstanding
+approval) now rides `ApplySession` instead of standing beside it.
+One object owns both halves: the approval binding admits one
+worker run, and any worker-staged intents the run leaves behind
+land as exactly one atomic batch through `Engine.apply_batch` —
+the same path the editor surface uses, so console writes are
+never a side-channel writer.
+
+Identity follows ADR-016: one live instance per (console,
+generation). `reset` retires the apply side (dropping buffered
+and staged intents), rotates the generation, kills every
+outstanding approval, and rearms the context for the next
+generation. `retire` from `ApplySession` is permanent and is
+only used inside `reset`, never by callers.
+"""
+
+import uuid
+
+from ..errors import ExecutionError
+from ..pyexec.apply_context import ApplySession
+
+CONTRACT_VERSION = "rocketeda/tooling/v0.1"
+
+_HELP = {
+    "run_drc": {
+        "signature": "run_drc(target, deck, profile?)",
+        "example": "op = run_drc(target='amplifier', deck='sky130A/decks.drc')",
+    },
+    "run_spice": {
+        "signature": "run_spice(netlist, benches, corners?)",
+        "example": "op = run_spice(netlist='amp_tb', benches=['ac', 'tran'])",
+    },
+    "python_execute": {
+        "signature": "python_execute(code_ref, profile)",
+        "example": "cell = python_execute(code_ref='analysis/fit.py', profile='design')",
+    },
+}
+
+
+def get_help(topic):
+    """Return versioned help metadata. Pure data — executes nothing.
+
+    Args:
+        topic: Help topic name (run_drc, run_spice, python_execute).
+
+    Returns:
+        Help entry with topic, contract version, signature, and
+            example.
+
+    Raises:
+        ExecutionError: unknown_topic for an unlisted topic.
+    """
+    try:
+        entry = _HELP[topic]
+    except KeyError:
+        raise ExecutionError("unknown_topic", f"Unknown help topic: {topic}.") from None
+    return {"topic": topic, "version": CONTRACT_VERSION, **entry}
+
+
+class ConsoleSession(ApplySession):
+    """Approval-bound console cells on one atomic apply-context.
+
+    The approval half pins one cell plus its context (full worker
+    source, history cursor, environment digest, expected revision);
+    admitting re-checks every field and any drift fails instead
+    of running a stranger's cell. The apply half stages worker
+    intent lines and emits one batch per outermost clean exit;
+    `land_worker_intents` drains a worker ops log and lands the
+    emitted batch through `Engine.apply_batch`.
+
+    Args:
+        project_id: Project this session approves cells for.
+        actor: Actor recorded on approvals.
+        console_id: Console owning this context; minted when
+            omitted.
+        pdk_name: PDK auto-activated at first block entry.
+        activate_pdk: Callable mapping the PDK name to proof;
+            a no-op activator when omitted.
+        resolve_layer: Callable mapping a layer spec to its lid;
+            the identity mapping when omitted.
+        emit: Callable receiving each outermost-exit batch;
+            batches accumulate on `emitted` when omitted.
+    """
+
+    def __init__(self, project_id, actor, console_id=None,
+                 pdk_name="sky130", activate_pdk=None,
+                 resolve_layer=None, emit=None):
+        self._actor = actor
+        self._approvals = {}
+        self._cursor = 0
+        self._emitted = []
+        super().__init__(
+            emit=emit if emit is not None else self._emitted.append,
+            project_id=project_id,
+            console_id=console_id or uuid.uuid4().hex,
+            generation=uuid.uuid4().hex,
+            pdk_name=pdk_name,
+            activate_pdk=(activate_pdk if activate_pdk is not None
+                          else (lambda name: {"pdk": name,
+                                              "activated": True})),
+            resolve_layer=(resolve_layer if resolve_layer is not None
+                           else (lambda spec: spec)),
+        )
+
+    @property
+    def console_id(self):
+        """Console owning this context (fixed for its lifetime).
+
+        Returns:
+            Console id string.
+        """
+        return self._console_id
+
+    @property
+    def generation(self):
+        """Current approval generation; reset retires it.
+
+        Reads and writes the generation the apply-context
+        stamps on every emitted batch, so approval fencing and
+        batch identity can never disagree.
+
+        Returns:
+            Generation id string.
+        """
+        return self._generation
+
+    @generation.setter
+    def generation(self, value):
+        """Sync the generation (for example, after a restart reload).
+
+        Args:
+            value: Generation id to fence on from here.
+        """
+        self._generation = value
+
+    @property
+    def emitted(self):
+        """Batches emitted so far, oldest first (evidence only).
+
+        Returns:
+            Emitted batch mappings in emission order.
+        """
+        return list(self._emitted)
+
+    def request_cell_approval(self, code, history_cursor, env_digest,
+                              expected_revision):
+        """Bind a pending approval to one cell plus its context.
+
+        Args:
+            code: Full worker source the approval pins.
+            history_cursor: History position the approval pins.
+            env_digest: Environment digest the approval pins.
+            expected_revision: Revision the approval pins.
+
+        Returns:
+            Approval record with approval_id and pending state.
+        """
+        approval_id = uuid.uuid4().hex
+        self._approvals[approval_id] = {
+            "approval_id": approval_id,
+            "code": code,
+            "history_cursor": history_cursor,
+            "env_digest": env_digest,
+            "expected_revision": expected_revision,
+            "state": "pending_approval",
+        }
+        return {"approval_id": approval_id, "state": "pending_approval"}
+
+    def _binding(self, approval_id):
+        """Return the live binding for one approval.
+
+        Args:
+            approval_id: Approval bound by request_cell_approval.
+
+        Returns:
+            Live approval record.
+
+        Raises:
+            ExecutionError: approval_invalid for an unknown or
+                expired approval.
+        """
+        try:
+            return self._approvals[approval_id]
+        except KeyError:
+            raise ExecutionError(
+                "approval_invalid", "Unknown or expired approval."
+            ) from None
+
+    def admit_cell(self, approval_id, code, history_cursor, env_digest,
+                   expected_revision):
+        """Admit a cell whose context still matches its binding.
+
+        Any drift in code, cursor, env, or revision fails instead
+        of running a stranger's cell. This is the seam the worker
+        lane (`CellRunner.run_cell`) admits through.
+
+        Args:
+            approval_id: Approval bound by request_cell_approval.
+            code: Full worker source to re-check against the binding.
+            history_cursor: History position to re-check.
+            env_digest: Environment digest to re-check.
+            expected_revision: Revision to re-check.
+
+        Returns:
+            Approval record with approval_id and approved state.
+
+        Raises:
+            ExecutionError: approval_invalid for an unknown approval
+                or any binding drift.
+        """
+        binding = self._binding(approval_id)
+        if (
+            binding["code"] != code
+            or binding["history_cursor"] != history_cursor
+            or binding["env_digest"] != env_digest
+            or binding["expected_revision"] != expected_revision
+        ):
+            raise ExecutionError(
+                "approval_invalid", "Approval no longer matches its binding."
+            )
+        binding["state"] = "approved"
+        return {"approval_id": approval_id, "state": "approved"}
+
+    def execute_cell(self, approval_id, code):
+        """Record a cell execution without running code.
+
+        The worker run itself happens in the worker lane (admitted
+        through `admit_cell`); landing worker-staged intents is
+        `land_worker_intents`, not this method.
+
+        Args:
+            approval_id: Approval whose code must match.
+            code: Cell code to re-check against the binding.
+
+        Returns:
+            Record with the advanced cursor and recorded state.
+
+        Raises:
+            ExecutionError: approval_invalid for an unknown approval
+                or code that differs from the approved code.
+        """
+        binding = self._binding(approval_id)
+        if binding["code"] != code:
+            raise ExecutionError(
+                "approval_invalid", "Cell code differs from the approved code."
+            )
+        self._cursor += 1
+        return {"cursor": self._cursor, "state": "recorded"}
+
+    def land_worker_intents(self, engine, ops_log_path, label):
+        """Drain worker intent lines and land one atomic batch.
+
+        Lines shaped ``{"apply_intent": {...}}`` in the worker ops
+        log join the session; anything else in the log is not ours
+        and stays unread. The staged intents emit as one batch at
+        the outermost exit and land through
+        `Engine.apply_batch` — one transaction, one revision.
+
+        Args:
+            engine: Engine landing the batch; when it has no
+                `apply_batch`, nothing is collected and None
+                returns.
+            ops_log_path: Worker ops-log path to drain.
+            label: Batch label carried on the envelope.
+
+        Returns:
+            Landing with ok True, the engine receipt, and the
+                intent count — or None when nothing was staged
+                or the engine cannot land.
+
+        Raises:
+            ProjectError: retired_session on a retired session;
+                invalid_command for an unknown sink kind;
+                revision_conflict when the head moved under the
+                batch.
+        """
+        land = getattr(engine, "apply_batch", None)
+        if land is None:
+            return None
+        staged = self.collect_ops(ops_log_path)
+        if staged == 0 and not self._staged:
+            return None
+        with self.edit(label):
+            pass
+        batch = self.last_batch
+        if batch is None:
+            return None
+        receipt = land(batch)
+        return {"ok": True, "receipt": receipt,
+                "intents": len(batch["intents"]), "label": batch["label"]}
+
+    def reset(self):
+        """Retire the generation and kill every outstanding approval.
+
+        The apply side retires too (buffered and staged intents
+        drop), then the context rearms under a fresh generation:
+        in-flight blocks must never span a reset — blocks are
+        synchronous, so a reset lands between cells, never inside
+        one.
+
+        Returns:
+            Mapping with the fresh generation id.
+        """
+        self.retire()
+        self._generation = uuid.uuid4().hex
+        self._approvals = {}
+        self._cursor = 0
+        self._retired = False
+        self._depth = 0
+        self._buffer = []
+        self._span = []
+        self._staged = []
+        self._pdk_active = False
+        return {"generation": self._generation}

rocket_engine/execution/console/lifecycle.py

@@ -0,0 +1,265 @@
+"""Console lifecycle: open/status/reset/close on the shared envelope.
+
+Identity plus generation, per the BWRAP-STUDY ruling: the console
+is a plain python console on trusted-local user permissions, every
+cell runs in a confined worker, and where bwrap is unprovable the
+surface still records generations and approvals but admits
+nothing. This module owns the recording half only — identity,
+generation rotation, workspace binding — and never spawns a
+worker, never touches the runner, and never changes sandbox
+behavior.
+
+Scoping decision (CONSOLE-LIFECYCLE): `stdio_console` keeps its
+local-panel REPL protocol (`submit`/`history`/`reset` over stdio);
+the Engine-side lifecycle operations (`python_open`,
+`python_execute`, `python_reset`) travel as shared-envelope
+command texts rendered here, so the adapt lane wires the three
+operations through `console_envelope`/`parse_console_envelope`
+without inventing a second envelope shape. The operations
+themselves are vocabulary/composition wiring (adapt lane); this
+module pins the envelope contract they must speak.
+
+Seam: `session_for` exposes the underlying `ConsoleSession` to the
+worker lane (`CellRunner.admit_cell`) and to tests; Engine wiring
+calls `open_console`/`reset_console` and never reaches past them.
+"""
+
+import uuid
+
+from ruamel.yaml import YAML
+
+from ..errors import ExecutionError
+from ..routing.calls import admission_envelope
+from .apply_session import ConsoleSession
+
+#: Lifecycle operations converging on the shared envelope. The
+#: Engine does not wire them yet (adapt lane); the envelope shape
+#: here is the contract that wiring must speak.
+CONSOLE_OPERATIONS = frozenset(
+    {"python_open", "python_execute", "python_reset"}
+)
+
+_yaml = YAML(typ="safe")
+
+
+def console_envelope(operation, arguments):
+    """Render one console lifecycle command on the shared envelope.
+
+    The text uses the identical YAML dumper the Engine uses for
+    every admission, so equal calls admit with equal identity and
+    console history replays as command scripts by construction.
+
+    Args:
+        operation: Console lifecycle operation (python_open,
+            python_execute, python_reset).
+        arguments: Operation arguments mapping.
+
+    Returns:
+        Envelope command text for the call.
+
+    Raises:
+        ExecutionError: invalid_command for an operation outside
+            the console lifecycle set or unserializable arguments.
+    """
+    if operation not in CONSOLE_OPERATIONS:
+        raise ExecutionError(
+            "invalid_command",
+            f"Not a console lifecycle operation: {operation!r}.",
+        )
+    if not isinstance(arguments, dict):
+        raise ExecutionError(
+            "invalid_command",
+            f"Envelope needs mapping arguments, got {arguments!r}.",
+        )
+    try:
+        return admission_envelope(operation, arguments)
+    except ExecutionError as exc:
+        raise ExecutionError("invalid_command", str(exc)) from exc
+
+
+def parse_console_envelope(text):
+    """Parse one console envelope back to operation + arguments.
+
+    Args:
+        text: Envelope command text from `console_envelope`.
+
+    Returns:
+        Mapping with operation and arguments.
+
+    Raises:
+        ExecutionError: invalid_command for unparsable text, a
+            non-mapping envelope, or an operation outside the
+            console lifecycle set.
+    """
+    if not isinstance(text, str) or not text.strip():
+        raise ExecutionError(
+            "invalid_command", "Console envelope must be text."
+        )
+    try:
+        document = _yaml.load(text)
+    except Exception as exc:
+        raise ExecutionError(
+            "invalid_command",
+            f"Console envelope does not parse: {exc}.",
+        ) from exc
+    if not isinstance(document, dict):
+        raise ExecutionError(
+            "invalid_command",
+            f"Console envelope must be a mapping, got {document!r}.",
+        )
+    operation = document.get("operation")
+    arguments = document.get("arguments")
+    if operation not in CONSOLE_OPERATIONS or not isinstance(
+        arguments, dict
+    ):
+        raise ExecutionError(
+            "invalid_command",
+            f"Not a console lifecycle envelope: {document!r}.",
+        )
+    return {"operation": operation, "arguments": dict(arguments)}
+
+
+class ConsoleLifecycle:
+    """Console identity + generation registry (lifecycle only).
+
+    `open_console` mints one console per call — or reuses the live
+    handle when the same workspace root opens again (single
+    console per panel). `reset_console` retires the generation and
+    kills every outstanding approval through the session; live
+    workers are cancel territory, never reset. Nothing here
+    executes: admission and execution stay in the worker lane.
+
+    Args:
+        None.
+    """
+
+    def __init__(self):
+        self._consoles = {}
+        self._roots = {}
+
+    def open_console(self, project_id, actor, workspace_root=None):
+        """Open a console, reusing the live one for its workspace.
+
+        Args:
+            project_id: Project the console approves cells for.
+            actor: Actor recorded on approvals.
+            workspace_root: Panel workspace binding; one live
+                handle per root, unbound when omitted.
+
+        Returns:
+            Opening with console_id, project_id, generation, and
+                the workspace_root binding (None when unbound).
+        """
+        if workspace_root is not None:
+            live = self._roots.get(str(workspace_root))
+            if live is not None and live in self._consoles:
+                record = self._consoles[live]
+                return self._describe(record)
+        console_id = uuid.uuid4().hex
+        session = ConsoleSession(project_id, actor)
+        record = {
+            "console_id": console_id,
+            "project_id": project_id,
+            "actor": actor,
+            "workspace_root": (
+                None if workspace_root is None
+                else str(workspace_root)
+            ),
+            "session": session,
+        }
+        self._consoles[console_id] = record
+        if record["workspace_root"] is not None:
+            self._roots[record["workspace_root"]] = console_id
+        return self._describe(record)
+
+    def status(self, console_id):
+        """Read one console's lifecycle state (never executes).
+
+        Args:
+            console_id: Console from `open_console`.
+
+        Returns:
+            Status with console_id, project_id, generation, and
+                the workspace_root binding.
+
+        Raises:
+            ExecutionError: unknown_console for an id never
+                opened or already closed.
+        """
+        return self._describe(self._record(console_id))
+
+    def session_for(self, console_id):
+        """Return the live session for worker-lane admission.
+
+        Worker-lane seam: `CellRunner.admit_cell` binds through
+        the session; Engine wiring never reaches past
+        `open_console`/`reset_console`.
+
+        Args:
+            console_id: Console from `open_console`.
+
+        Returns:
+            Live `ConsoleSession` for the console.
+
+        Raises:
+            ExecutionError: unknown_console for an id never
+                opened or already closed.
+        """
+        return self._record(console_id)["session"]
+
+    def reset_console(self, console_id):
+        """Retire the generation; kill every outstanding approval.
+
+        Args:
+            console_id: Console from `open_console`.
+
+        Returns:
+            Mapping with the console_id and the fresh generation.
+
+        Raises:
+            ExecutionError: unknown_console for an id never
+                opened or already closed.
+        """
+        record = self._record(console_id)
+        outcome = record["session"].reset()
+        return {
+            "console_id": console_id,
+            "generation": outcome["generation"],
+        }
+
+    def close_console(self, console_id):
+        """Close a console and release its workspace binding.
+
+        Args:
+            console_id: Console from `open_console`.
+
+        Returns:
+            Closing with console_id and closed True.
+
+        Raises:
+            ExecutionError: unknown_console for an id never
+                opened or already closed.
+        """
+        record = self._record(console_id)
+        del self._consoles[console_id]
+        root = record["workspace_root"]
+        if root is not None and self._roots.get(root) == console_id:
+            del self._roots[root]
+        return {"console_id": console_id, "closed": True}
+
+    def _record(self, console_id):
+        try:
+            return self._consoles[console_id]
+        except KeyError:
+            raise ExecutionError(
+                "unknown_console", f"Unknown console: {console_id!r}."
+            ) from None
+
+    @staticmethod
+    def _describe(record):
+        return {
+            "console_id": record["console_id"],
+            "project_id": record["project_id"],
+            "generation": record["session"].generation,
+            "workspace_root": record["workspace_root"],
+        }