rocket-engine

_{Part of RocketIDE · the engine}

rocket-engine is RocketEDA's headless Python engine for chip-design projects. It owns the shared operation surface, project revisions and events, tool dispatch, capability reporting, and verification evidence used by manual clients and the agent harness.

The product serves digital, analog, photonic, and mixed-domain work. The engine coordinates existing EDA tools through adapters; it does not implement an agent loop or physics solvers. Product direction lives in the sibling PRD. The agent harness is in rocket_fuel, the current workbench is in UIUX, and RocketIDE is the planned packaging layer.

Requirements

pip ships the engine, not the tools. Native binaries, PDK trees, and cloud keys arrive via provision recipes, your own PATH, or explicit opt-in. The engine resolves provisioned roots first, then ambient PATH, then per-job tool_dir; report_capabilities tells you exactly what resolved and the remedy for what did not.

Native tools (provision or PATH)

Python libraries (ride the wheel)

PDKs (registered trees, never in the wheel)

Cloud (opt-in only, never default)

Current shape

• src/ is the package root and installs as rocket_engine.
• composition.py is the composition root. It binds project and execution services, operation/query handlers, and solver adapters.
• Transports use the same operation vocabulary. The live CLI and MCP server are implemented. HTTP and IPC currently provide JSON envelope handlers; listening servers, SSE delivery, and length-prefixed IPC framing are not implemented here.
• Project mutations are revision-gated and actor-attributed. A durable project ledger is available when an engine root is configured; an engine without one keeps project state in memory.
• Engine submit runs normal solver operations inline and returns their completion. run_job remains the explicit deferred/batch pump and idempotent completion fetch.
• Tool registration describes what the engine can route. Machine-specific availability and PDK/deck readiness come from get_capabilities; registration alone does not mean a flow is qualified or installed.

Architecture

UI / CLI / Rocket Fuel
        │
  adapters/{http,ipc,mcp,cli}
        │ commands and queries
  composition.Engine
        ├── project/     revisions, documents, components, events
        ├── execution/   dispatch, isolation, run state, verdicts
        ├── library/     PDK and cell catalogs
        └── workflows/   D/A/P/M check plans and completion gates
                │
       adapters/<solver> ──> native EDA tools and Python libraries
                │
        normalized findings, measurements, artifacts

interfaces/ defines the shared vocabulary, data shapes, and ports. Transport adapters translate client requests into engine calls. Solver adapters preflight project inputs, invoke tools, and normalize their output. The engine evaluates findings and publishes project events; transports do not own verification rules.

Registered solver operations

This is a routing map, not a support guarantee. Consult get_capabilities for installed tools, profiles, PDKs, and decks. The LibreLane adapter is registered and has hermetic coverage; its live RTL-to-GDS qualification is currently blocked on the pinned LibreLane distribution and a compatible PDK root. See the DIGITAL-FLOW report and the sprint board for current work status.

API contract

Next implementation contract: the v1 contract bundle freezes six methods (describe, query, edit, run, script, watch), typed editors/components/testbenches, tool tasks and canvas.toml. It includes generated client types/help and validated examples. Provider and consumer migration is pending; the current running API below is v0. ADR-014 records the supersession and deployment gates. Check the design contract with .venv/bin/python scripts/check_v1_contract.py.

The operation and query vocabulary is in src/interfaces/vocabulary.py. Handler docstrings are the source for the generated docs/engine-api.md, docs/api-schema.json, and docs/api-help.json. Do not hand-edit those generated files; regenerate them with scripts/api_spec.py --write.

Every accepted mutation checks expected_revision, advances the project revision, and records its actor. A stale revision returns revision_conflict; callers re-read and retry. Run verdicts are engine-owned. Exit status and tool process output alone never establish PASS.

The current MCP bridge derives descriptions from handler docstrings. Its wire input schemas are still generic for most tools; only python_execute currently has a specific schema. See MCP-SCHEMA.

Setup and common commands

Use the repository installer as the only supported Python environment setup. It creates the pinned Python 3.12 environment, installs the base and development dependencies, installs a sealed engine copy, registers the configured PDK, and probes selected host tools.

scripts/install.sh --install
.venv/bin/python -m rocket_engine --help
scripts/install.sh --check-only

Native tool provisioning is documented in docs/provision-plan.md and managed by scripts/provision_toolchain.sh. get_capabilities reports what is usable on the current machine. After editing src/, rerun scripts/install.sh --install so the sealed package matches the source tree.

For operation docstring and generated-contract conventions, read AGENTS.md. It also documents the test and fixture workflow. The scenario guide describes live-tool prerequisites and the scenario CLI.

Where to look next

• Project requirements and decisions: ../PRD/README.md
• Current engine work and open tickets: docs/sprint-board.md, docs/tickets/
• Fuel integration contract: docs/fuel-contract.md
• Generated engine API: docs/engine-api.md
• Storage ownership: docs/storage-policy.md and docs/adr/