rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/execution/README.md

@@ -0,0 +1,30 @@
+# execution — run lifecycle, isolation, and verdicts
+
+`execution/` provides run-state services and execution helpers used by the engine composition root. It covers admission/backpressure, solver process isolation, the Python execution approval surface, normalized evidence, and verdict evaluation. It contains no UI code and owns no solver-specific parsing.
+
+## Main pieces
+
+- `service.py`: in-memory run and approval records, cancellation state, evidence/findings access, and verdict evaluation. Run records live for the lifetime of the `Engine` instance.
+- `apig_pool.py`, `coalesce.py`, and `block_runs_scope.py`: bounded dispatch, duplicate-submit coalescing, and block-scoped run input handling.
+- `runner.py`: subprocess helpers and `BwrapRunner` for OS-level tool isolation when the host supports the required sandbox.
+- `replay_safe.py`: reports interrupted runs after restart and requires an explicit resume or discard decision; it does not silently re-execute survivors.
+- `python_exec.py` and `console.py`: project-script/console request handling and approval-binding semantics. `python_execute` requests admission; the caller cannot approve its own code.
+- `dispatch.py`: shared operation-call parsing and dispatch used by the CLI and console paths.
+
+## Run flow
+
+`Engine.submit` validates and admits a solver operation, captures its project context, dispatches the selected adapter, and normally returns the completed result inline. `run_job` is available for deferred work, pool draining, batch pumping, and idempotent retrieval of an admitted run's completion. The two surfaces share the same run IDs and verdict rules.
+
+Solver adapters return structured findings, measurements, and artifacts. The engine evaluates those results into `PASS`, `FAIL`, `NOT_RUN`, or `UNSUPPORTED`; a zero process exit does not establish `PASS`. Missing isolation support disables isolated work instead of falling back to an unrestricted host process.
+
+## Persistence boundary
+
+The project ledger can persist when `engine_root` is configured, but `ExecutionService` run state and captured logs are in-memory per engine instance. The MCP launcher can write completed run evidence under the bound project's `results/engine-runs/`. These are separate lifecycles; do not assume every queue item or log survives an engine restart.
+
+## Routing
+
+- Project revisions/events → [`project/`](../project/README.md).
+- Result and command records → [`interfaces/`](../interfaces/README.md).
+- Tool invocation and parsing → [`adapters/`](../adapters/README.md).
+- Process ordering and the fully-verified gate → [`workflows/`](../workflows/README.md).
+- Isolation and console contracts → [Python console spec](../../../PRD/tools-research/python-console-spec.md).

rocket_engine/execution/__init__.py

@@ -0,0 +1,150 @@
+"""Admission, queue, dispatch, isolated workers, cancel, evidence, evaluation. Owns execution."""
+
+from .apig.pool import (
+    ApigPool,
+    pending_from_events,
+    request_for_run,
+    stored_completion_from_events,
+)
+from .apig.submit import SubmitImmediate, merge_ack_completion
+from .block_runs_scope import (
+    BLOCK_RUN_OPERATIONS,
+    BLOCK_SCOPE,
+    PROJECT_SCOPE,
+    SUPPORTED_SCOPES,
+    BlockScopeError,
+    build_scope_record,
+    check_operation_scope,
+    closure_hash,
+    narrow_job_for_block,
+    parse_target,
+    resolve_block,
+    scope_provenance,
+    snapshot_closure,
+    stamp_verdict,
+)
+from .coalesce import (
+    Coalescer,
+    content_key,
+    deck_hash,
+    normalize_arguments,
+)
+from .console.apply_session import ConsoleSession, get_help
+from .routing.calls import (
+    CONSOLE_TOOL_VERBS,
+    TIER_2_OPERATIONS,
+    admission_envelope,
+    build_effects_report,
+    collect_run_ids,
+    entity_doc_path,
+    format_address,
+    is_tier2,
+    parse_address,
+    report_completions,
+    stamp_tier2_call,
+    tier_for,
+    tool_call,
+)
+from .routing.namespace import ConsoleNamespace
+from .routing.tools import ConsoleTools
+from .dispatch import OpDispatcher, parse_op_call, parse_op_tokens
+from .errors import ExecutionError, UsageError
+from .python_exec import (
+    MCP_INPUT_SCHEMA,
+    PythonExecRunner,
+    PythonExecService,
+    build_worker_source,
+    not_run_verdict,
+    parse_exception,
+    prelude_digest_for,
+    resolve_script_path,
+)
+from .replay_safe import (
+    AMBIGUOUS,
+    POISON,
+    POISON_THRESHOLD,
+    REPLAY_SAFE_VERSION,
+    RETRYABLE,
+    ReplaySafe,
+    boot_message,
+    content_key_for,
+    interrupt_counts_from_events,
+    survivors_from_events,
+    user_message_for,
+)
+from .runner import BwrapRunner
+from .service import ExecutionService
+from .worker import CellRunner, CredentialGate, worker_profile
+
+__all__ = [
+    "AMBIGUOUS",
+    "BLOCK_RUN_OPERATIONS",
+    "BLOCK_SCOPE",
+    "POISON",
+    "POISON_THRESHOLD",
+    "PROJECT_SCOPE",
+    "REPLAY_SAFE_VERSION",
+    "RETRYABLE",
+    "SUPPORTED_SCOPES",
+    "ApigPool",
+    "BlockScopeError",
+    "BwrapRunner",
+    "CellRunner",
+    "Coalescer",
+    "CONSOLE_TOOL_VERBS",
+    "ConsoleNamespace",
+    "ConsoleSession",
+    "ConsoleTools",
+    "CredentialGate",
+    "ExecutionError",
+    "ExecutionService",
+    "MCP_INPUT_SCHEMA",
+    "OpDispatcher",
+    "PythonExecRunner",
+    "PythonExecService",
+    "ReplaySafe",
+    "SubmitImmediate",
+    "TIER_2_OPERATIONS",
+    "UsageError",
+    "admission_envelope",
+    "boot_message",
+    "build_effects_report",
+    "build_scope_record",
+    "build_worker_source",
+    "check_operation_scope",
+    "closure_hash",
+    "collect_run_ids",
+    "content_key",
+    "deck_hash",
+    "content_key_for",
+    "entity_doc_path",
+    "format_address",
+    "get_help",
+    "interrupt_counts_from_events",
+    "is_tier2",
+    "merge_ack_completion",
+    "narrow_job_for_block",
+    "normalize_arguments",
+    "not_run_verdict",
+    "parse_address",
+    "parse_exception",
+    "parse_op_call",
+    "parse_op_tokens",
+    "prelude_digest_for",
+    "report_completions",
+    "resolve_script_path",
+    "parse_target",
+    "pending_from_events",
+    "request_for_run",
+    "resolve_block",
+    "scope_provenance",
+    "snapshot_closure",
+    "stamp_tier2_call",
+    "stamp_verdict",
+    "stored_completion_from_events",
+    "survivors_from_events",
+    "tier_for",
+    "tool_call",
+    "user_message_for",
+    "worker_profile",
+]

rocket_engine/execution/apig/__init__.py

@@ -0,0 +1 @@
+"""Admission pool: backlog, backpressure, and submit-immediate."""

rocket_engine/execution/apig/pool.py

@@ -0,0 +1,463 @@
+"""Worker pool (API-GENERALIZE): in-order drain, backpressure, boot replay.
+
+The durable request log (ProjectService) owns admission truth; the pool
+owns execution order around it. `submit_request` delegates admission to
+the ledger (same ack bytes, same `request_id` dedupe), then holds the
+admitted run in a FIFO backlog until `drain`/`drain_ids` runs it through
+the caller-supplied runner. The backlog is bounded: a full pool refuses
+new admissions with a typed `pool_full` error BEFORE touching the
+ledger, so a refusal never advances the revision and nothing is ever
+silently dropped. Replays (same `request_id`, same text) return the
+stored ack without re-enqueueing and are never refused, even when full.
+
+Boot replay rebuilds the backlog from ledger events alone: `replay`
+takes `job_queued` run ids in seq order, minus every run id with a
+`run_completed`/`run_failed` event, resolves each survivor through the
+caller, and drains them — so a kill mid-queue still completes every
+request exactly once after reboot.
+"""
+
+import threading
+from concurrent.futures import ThreadPoolExecutor
+
+from ruamel.yaml import YAML
+
+try:
+    from ..errors import ExecutionError
+except ImportError:  # standalone verification before install
+    from rocket_engine.execution.errors import ExecutionError
+
+POOL_VERSION = 1
+DEFAULT_MAX_DEPTH = 64
+DEFAULT_MAX_WORKERS = 4
+
+_yaml = YAML(typ="safe")
+
+
+def pending_from_events(events):
+    """Order admitted-but-uncompleted requests oldest first.
+
+    Args:
+        events: Ledger events with seq, event, request_id, and
+            data.run_id entries.
+
+    Returns:
+        (request_id, run_id) pairs for every `job_queued` event
+            without a later `run_completed`/`run_failed` event for
+            the same run id, in seq order.
+    """
+    queued = {}
+    order = []
+    completed = set()
+    for event in sorted(events, key=lambda e: e.get("seq", 0)):
+        data = event.get("data") or {}
+        run_id = data.get("run_id")
+        if run_id is None:
+            continue
+        if event.get("event") == "job_queued":
+            if run_id not in queued:
+                order.append(run_id)
+            queued[run_id] = event.get("request_id")
+        elif event.get("event") in ("run_completed", "run_failed"):
+            completed.add(run_id)
+    return [
+        (queued[run_id], run_id) for run_id in order if run_id not in completed
+    ]
+
+
+def stored_completion_from_events(events, run_id):
+    """Read a run's stored completion from ledger events, if any.
+
+    Args:
+        events: Ledger events with event and data entries.
+        run_id: Run to look up.
+
+    Returns:
+        Completion mapping (run_id, completed state, verdict,
+            operation) from the run's `run_completed`/`run_failed`
+            event, or None when the run never completed.
+    """
+    for event in events:
+        if event.get("event") not in ("run_completed", "run_failed"):
+            continue
+        data = event.get("data") or {}
+        if data.get("run_id") != run_id:
+            continue
+        return {
+            "run_id": run_id,
+            "state": "completed",
+            "verdict": data.get("verdict"),
+            "operation": data.get("operation"),
+        }
+    return None
+
+
+def request_for_run(events, run_id):
+    """Find the admitting request id for a run, if any.
+
+    Args:
+        events: Ledger events with event, request_id, and
+            data.run_id entries.
+        run_id: Run to trace back to its admission.
+
+    Returns:
+        Request id from the run's `job_queued` event, or None
+            when no admission event names the run.
+    """
+    for event in events:
+        if event.get("event") != "job_queued":
+            continue
+        data = event.get("data") or {}
+        if data.get("run_id") == run_id:
+            return event.get("request_id")
+    return None
+
+
+class ApigPool:
+    """Bounded FIFO execution pool over a durable request ledger.
+
+    Args:
+        project: Project port with `submit(command_text,
+            request_id, expected_revision)`, `events_since(cursor)`,
+            and `command_for(request_id)` (ProjectService serves).
+        runner: Callable `(operation, arguments, snapshot_id,
+            request_id, run_id)` returning a completion mapping.
+            Runner exceptions are recorded as failed completions,
+            never raised, and the drain continues.
+        max_depth: Maximum undrained backlog; admissions past it
+            are refused with `pool_full`, never queued, never
+            dropped silently.
+        max_workers: Drain fan-out for independent items
+            (BATCH-PARALLEL). Reads and sims run concurrently;
+            same-entity mutations serialize upstream through
+            ENTITY-CAS. 1 keeps the legacy sequential drain.
+
+    Caution: The bound applies to new admissions only — replay
+        re-enqueues crash survivors past the bound rather than
+        abandoning admitted work.
+    """
+
+    def __init__(self, project, runner, max_depth=DEFAULT_MAX_DEPTH,
+                 max_workers=1):
+        self._project = project
+        self._runner = runner
+        self._max_depth = max_depth
+        self._max_workers = max(1, int(max_workers))
+        self._lock = threading.Lock()
+        self._backlog = []
+        self._queued = {}
+        self._acks = {}
+        self._completions = {}
+        self._completed_runs = None
+        self._discarded = set()
+
+    @property
+    def max_depth(self):
+        """Backlog bound refused past, not queued past.
+
+        Returns:
+            Maximum undrained backlog.
+        """
+        return self._max_depth
+
+    @property
+    def depth(self):
+        """Current undrained backlog size.
+
+        Returns:
+            Number of admitted runs awaiting drain.
+        """
+        with self._lock:
+            return len(self._backlog)
+
+    def _seed_completed(self):
+        if self._completed_runs is None:
+            self._completed_runs = {
+                run_id
+                for _request_id, run_id in ()
+            }
+            for event in self._project.events_since(0):
+                if event.get("event") in ("run_completed", "run_failed"):
+                    data = event.get("data") or {}
+                    if data.get("run_id") is not None:
+                        self._completed_runs.add(data["run_id"])
+
+    def submit_request(self, command_text, request_id, expected_revision=None):
+        """Admit one request through the ledger, then enqueue it.
+
+        Replays return the stored ack without re-enqueueing and are
+        never refused. A full pool raises before admission, so the
+        ledger never advances for a refused request.
+
+        Args:
+            command_text: YAML command mapping with an operation.
+            request_id: Client envelope id; resubmitting the
+                identical text returns the identical ack.
+            expected_revision: Revision the writer read.
+
+        Returns:
+            Admission ack with run_id, snapshot_id, queued state,
+                current revision, and event cursor.
+
+        Raises:
+            ExecutionError: pool_full when the undrained backlog
+                is at its bound — names the request, the depth,
+                and the bound.
+            ProjectError: invalid_yaml, revision_conflict, or
+                request_conflict from the ledger, untouched.
+        """
+        with self._lock:
+            if request_id in self._acks:
+                return dict(self._acks[request_id])
+            if len(self._backlog) >= self._max_depth:
+                raise ExecutionError(
+                    "pool_full",
+                    f"Pool saturated: {request_id} refused at "
+                    f"depth {len(self._backlog)}/{self._max_depth}; "
+                    "drain before submitting more.",
+                    fields=[{"depth": len(self._backlog),
+                             "max_depth": self._max_depth}],
+                )
+        ack = self._project.submit(
+            command_text, request_id, expected_revision=expected_revision
+        )
+        self._seed_completed()
+        command = _yaml.load(command_text)
+        with self._lock:
+            self._acks[request_id] = dict(ack)
+            if ack["run_id"] in self._completed_runs:
+                return dict(ack)
+            self._enqueue_locked(
+                request_id, ack["run_id"], command, ack["snapshot_id"]
+            )
+        return dict(ack)
+
+    def adopt(self, request_id, run_id, command, snapshot_id):
+        """Enqueue an already-admitted request without touching the ledger.
+
+        Batch pumping and boot replay admit through this: the
+        request was admitted before (its ack lives in the ledger),
+        so only the backlog bound and dedupe apply here.
+
+        Args:
+            request_id: Admitting envelope id.
+            run_id: Admitted run id.
+            command: Parsed command mapping with operation and
+                arguments.
+            snapshot_id: Evidence snapshot the run pins.
+
+        Returns:
+            True when the run was enqueued, False when it was
+                already queued or drained.
+
+        Raises:
+            ExecutionError: pool_full when the undrained backlog
+                is at its bound.
+        """
+        with self._lock:
+            if request_id in self._queued or request_id in self._completions:
+                return False
+            self._seed_completed()
+            if run_id in self._completed_runs:
+                return False
+            if len(self._backlog) >= self._max_depth:
+                raise ExecutionError(
+                    "pool_full",
+                    f"Pool saturated: {request_id} refused at "
+                    f"depth {len(self._backlog)}/{self._max_depth}; "
+                    "drain before submitting more.",
+                    fields=[{"depth": len(self._backlog),
+                             "max_depth": self._max_depth}],
+                )
+            self._enqueue_locked(request_id, run_id, command, snapshot_id)
+        return True
+
+    def _enqueue(self, request_id, run_id, command, snapshot_id):
+        with self._lock:
+            self._enqueue_locked(request_id, run_id, command, snapshot_id)
+
+    def _enqueue_locked(self, request_id, run_id, command, snapshot_id):
+        entry = {
+            "request_id": request_id,
+            "run_id": run_id,
+            "operation": command.get("operation"),
+            "arguments": dict(command.get("arguments") or {}),
+            "snapshot_id": snapshot_id,
+        }
+        self._backlog.append(entry)
+        self._queued[request_id] = entry
+
+    def pending(self):
+        """List undrained run ids, oldest first.
+
+        Returns:
+            Run ids in drain order.
+        """
+        with self._lock:
+            return [entry["run_id"] for entry in self._backlog]
+
+    def drain(self, limit=None):
+        """Run undrained entries oldest first.
+
+        Args:
+            limit: Maximum completions; the whole backlog when
+                omitted.
+
+        Returns:
+            Completion mappings in drain order. A raising runner
+                becomes a failed completion carrying the error,
+                and the drain continues past it.
+        """
+        with self._lock:
+            run_ids = [entry["run_id"] for entry in self._backlog]
+        if limit is not None:
+            run_ids = run_ids[: max(0, limit)]
+        return self.drain_ids(run_ids)
+
+    def discard(self, run_id):
+        """Drop one undrained backlog entry without running it.
+
+        Cancel-before-drain uses this: the admission stands in the
+        ledger, but the run never executes here. A later drain of
+        the same id returns a cancelled (NOT_RUN) completion; a
+        drain of an id never admitted still raises
+        unknown_request.
+
+        Args:
+            run_id: Backlog run id to drop.
+
+        Returns:
+            True when an entry was dropped, False when no backlog
+            entry names the id.
+        """
+        with self._lock:
+            for entry in self._backlog:
+                if entry["run_id"] == run_id:
+                    self._backlog.remove(entry)
+                    del self._queued[entry["request_id"]]
+                    self._discarded.add(run_id)
+                    return True
+        return False
+
+    def drain_ids(self, run_ids):
+        """Run named backlog entries in the given order.
+
+        With max_workers > 1 the runners overlap (BATCH-PARALLEL);
+        results still return in the given order.
+
+        Args:
+            run_ids: Backlog run ids to drain, in order.
+
+        Returns:
+            Completion mappings in the given order.
+
+        Raises:
+            ExecutionError: unknown_request for a run id with no
+                backlog entry.
+        """
+        cancelled_ids = []
+        with self._lock:
+            entries = []
+            for run_id in run_ids:
+                entry = None
+                for candidate in self._backlog:
+                    if candidate["run_id"] == run_id:
+                        entry = candidate
+                        break
+                if entry is None:
+                    if run_id in self._discarded:
+                        cancelled_ids.append(run_id)
+                        continue
+                    raise ExecutionError(
+                        "unknown_request", f"No queued request: {run_id}."
+                    )
+                self._backlog.remove(entry)
+                del self._queued[entry["request_id"]]
+                entries.append(entry)
+        by_id = {}
+        for run_id in cancelled_ids:
+            by_id[run_id] = {
+                "run_id": run_id,
+                "state": "cancelled",
+                "reason": "cancelled before dispatch",
+                "verdict": {
+                    "status": "NOT_RUN",
+                    "reason": "cancelled before dispatch",
+                },
+            }
+        if entries:
+            if self._max_workers <= 1 or len(entries) <= 1:
+                drained = [self._drain_one(entry) for entry in entries]
+            else:
+                with ThreadPoolExecutor(
+                    max_workers=min(self._max_workers, len(entries)),
+                    thread_name_prefix="apig-drain",
+                ) as pool:
+                    drained = list(pool.map(self._drain_one, entries))
+            for entry, completion in zip(entries, drained):
+                by_id.setdefault(entry["run_id"], completion)
+        return [by_id[run_id] for run_id in run_ids]
+
+    def _drain_one(self, entry):
+        """Run one backlog entry, recording its completion."""
+        try:
+            completion = self._runner(
+                entry["operation"],
+                dict(entry["arguments"]),
+                entry["snapshot_id"],
+                entry["request_id"],
+                entry["run_id"],
+            )
+        except Exception as exc:  # noqa: BLE001 — recorded, never raised
+            code = getattr(exc, "code", type(exc).__name__)
+            completion = {
+                "run_id": entry["run_id"],
+                "state": "failed",
+                "error": f"{code}: {exc}",
+                "operation": entry["operation"],
+            }
+        with self._lock:
+            self._completions[entry["request_id"]] = completion
+            self._seed_completed()
+            self._completed_runs.add(entry["run_id"])
+        return completion
+
+    def replay(self, events, resolve):
+        """Re-enqueue crash survivors from ledger events, then drain them.
+
+        Args:
+            events: Ledger events; survivors are `job_queued` run
+                ids without a `run_completed`/`run_failed` event.
+            resolve: Callable `request_id -> (command, ack)` for
+                each survivor (ProjectService.command_for serves).
+
+        Returns:
+            Report with replayed run ids (seq order), their
+                completions, and skipped entries (each with
+                request_id, run_id, and reason) for survivors the
+                resolver cannot serve. Skips are reported, never
+                silent, and the drain continues past them.
+        """
+        replayed = []
+        skipped = []
+        for request_id, run_id in pending_from_events(events):
+            if request_id in self._queued or request_id in self._completions:
+                continue
+            try:
+                command, ack = resolve(request_id)
+            except Exception as exc:  # noqa: BLE001 — reported per request
+                skipped.append({
+                    "request_id": request_id,
+                    "run_id": run_id,
+                    "reason": f"{getattr(exc, 'code', type(exc).__name__)}: {exc}",
+                })
+                continue
+            self._acks[request_id] = dict(ack)
+            self._enqueue(request_id, run_id, command, ack["snapshot_id"])
+            replayed.append(run_id)
+        completions = self.drain_ids(replayed)
+        return {
+            "replayed": replayed,
+            "completions": completions,
+            "skipped": skipped,
+        }