rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/workflows/viewsync.py

@@ -0,0 +1,399 @@
+"""Intended-vs-extracted view comparison (VIEW-SYNC, photonic P14).
+
+`compare_views` reduces two schematics through the shared
+CONNECT-GRAPH extraction (`prepare_netlist_structs`), correlates
+pins through CellLink identity (never a second naming scheme),
+and reports missing/wrong/extra ports, missing/unexpected
+connections, and unmapped objects with per-finding identity
+references. Every net name flows from the cited view's shared
+`Connectivity.net_name` authority.
+"""
+
+import json
+
+from ..interfaces.celllink import REFERENCE, ContractError, resolve_link
+from .connectgraph import ConnectGraphError, prepare_netlist_structs
+
+RULE_MISSING_PORT = "view_sync.missing_port"
+RULE_EXTRA_PORT = "view_sync.extra_port"
+RULE_WRONG_PORT = "view_sync.wrong_port"
+RULE_MISSING_CONNECTION = "view_sync.missing_connection"
+RULE_UNEXPECTED_CONNECTION = "view_sync.unexpected_connection"
+RULE_UNMAPPED = "view_sync.unmapped"
+
+
+class ViewSyncError(ValueError):
+    """Bad view-sync input: malformed view or bad identity mapping."""
+
+
+def _identity_maps(links, variant):
+    """Per-instance symbol-to-cell maps plus their inverses."""
+    if links is None:
+        links = []
+    if not isinstance(links, list):
+        raise ViewSyncError(f"links must be a list, got {links!r}.")
+    base_variant = variant in (None, REFERENCE)
+    if not base_variant:
+        if not isinstance(variant, str) or not variant:
+            raise ViewSyncError(
+                f"variant must be a non-empty string, got {variant!r}."
+            )
+        if not links:
+            raise ViewSyncError(f"Unknown variant {variant!r}: no links define it.")
+    forward = {}
+    for index, entry in enumerate(links):
+        if not isinstance(entry, dict):
+            raise ViewSyncError(f"links[{index}] must be a mapping, got {entry!r}.")
+        block_id = entry.get("id")
+        if not isinstance(block_id, str) or not block_id:
+            raise ViewSyncError(f"links[{index}] needs a non-empty string id.")
+        if block_id in forward:
+            raise ViewSyncError(f"Duplicate link id: {block_id!r}.")
+        block = {"id": block_id}
+        if "CellLink" in entry:
+            block["CellLink"] = entry["CellLink"]
+        try:
+            resolved = resolve_link(block, variant=variant)
+        except ContractError as exc:
+            raise ViewSyncError(f"link {block_id!r}: {exc}") from exc
+        mapping = {item["symPin"]: item["cellPin"] for item in resolved["pinMap"]}
+        targets = sorted(mapping.values())
+        if len(set(targets)) != len(targets):
+            raise ViewSyncError(
+                f"link {block_id!r}: pinMap collision: two symbol pins "
+                f"resolve to one cell pin ({', '.join(targets)})."
+            )
+        forward[block_id] = mapping
+    reverse = {
+        name: {cell: sym for sym, cell in mapping.items()}
+        for name, mapping in forward.items()
+    }
+    return forward, reverse
+
+
+def _extract_side(schematic, side):
+    """Extract one view, naming the side on failure."""
+    try:
+        return prepare_netlist_structs(schematic)
+    except ConnectGraphError as exc:
+        raise ViewSyncError(f"{side} schematic: {exc}") from exc
+
+
+def _net_id_by_name(connectivity, name, side):
+    """Net id for a port name (ports always name an extracted net)."""
+    for net in connectivity.nets:
+        if net.name == name:
+            return net.id
+    raise ViewSyncError(f"{side} port {name!r} names no extracted net.")
+
+
+def _port_findings(intended_structs, extracted_structs):
+    """Missing/wrong/extra port findings with authority net names."""
+    findings = []
+    iconn = intended_structs.connectivity
+    econn = extracted_structs.connectivity
+    intended_ports = {p["name"]: p["direction"] for p in intended_structs.ports}
+    extracted_ports = {p["name"]: p["direction"] for p in extracted_structs.ports}
+    for name in sorted(set(intended_ports) - set(extracted_ports)):
+        net_id = _net_id_by_name(iconn, name, "intended")
+        findings.append(
+            {
+                "rule": RULE_MISSING_PORT,
+                "severity": "error",
+                "message": (
+                    f"port {name} is missing in extracted "
+                    f"(intended direction {intended_ports[name]})"
+                ),
+                "view": "intended",
+                "port": name,
+                "expected_direction": intended_ports[name],
+                "net": iconn.net_name(net_id),
+                "net_id": net_id,
+            }
+        )
+    for name in sorted(set(extracted_ports) - set(intended_ports)):
+        net_id = _net_id_by_name(econn, name, "extracted")
+        findings.append(
+            {
+                "rule": RULE_EXTRA_PORT,
+                "severity": "error",
+                "message": (
+                    f"port {name} is unexpected in extracted "
+                    f"(direction {extracted_ports[name]})"
+                ),
+                "view": "extracted",
+                "port": name,
+                "actual_direction": extracted_ports[name],
+                "net": econn.net_name(net_id),
+                "net_id": net_id,
+            }
+        )
+    for name in sorted(set(intended_ports) & set(extracted_ports)):
+        if intended_ports[name] == extracted_ports[name]:
+            continue
+        intended_id = _net_id_by_name(iconn, name, "intended")
+        extracted_id = _net_id_by_name(econn, name, "extracted")
+        findings.append(
+            {
+                "rule": RULE_WRONG_PORT,
+                "severity": "error",
+                "message": (
+                    f"port {name} direction {extracted_ports[name]}, "
+                    f"expected {intended_ports[name]}"
+                ),
+                "view": "extracted",
+                "port": name,
+                "expected_direction": intended_ports[name],
+                "actual_direction": extracted_ports[name],
+                "net": econn.net_name(extracted_id),
+                "net_id": extracted_id,
+                "intended_net_id": intended_id,
+                "extracted_net_id": extracted_id,
+            }
+        )
+    return findings
+
+
+def _correlate(intended_structs, extracted_structs, forward, reverse):
+    """Correlate pins through CellLink identity (mapped + unmapped)."""
+    intended_by_inst = {i.name: i for i in intended_structs.instances}
+    extracted_by_inst = {i.name: i for i in extracted_structs.instances}
+    findings = []
+    for name in sorted(set(intended_by_inst) - set(extracted_by_inst)):
+        pins = sorted(p for p, _ in intended_by_inst[name].pins)
+        findings.append(
+            {
+                "rule": RULE_UNMAPPED,
+                "severity": "error",
+                "message": (
+                    f"instance {name} has no extracted counterpart "
+                    f"({len(pins)} pins)"
+                ),
+                "view": "intended",
+                "kind": "instance",
+                "instance": name,
+                "side": "intended",
+                "pins": pins,
+            }
+        )
+    for name in sorted(set(extracted_by_inst) - set(intended_by_inst)):
+        pins = sorted(p for p, _ in extracted_by_inst[name].pins)
+        findings.append(
+            {
+                "rule": RULE_UNMAPPED,
+                "severity": "error",
+                "message": (
+                    f"instance {name} has no intended counterpart "
+                    f"({len(pins)} pins)"
+                ),
+                "view": "extracted",
+                "kind": "instance",
+                "instance": name,
+                "side": "extracted",
+                "pins": pins,
+            }
+        )
+    mapped = []
+    for name in sorted(set(intended_by_inst) & set(extracted_by_inst)):
+        pin_map = forward.get(name, {})
+        back_map = reverse.get(name, {})
+        intended_pins = {p: n for p, n in intended_by_inst[name].pins}
+        extracted_pins = {p: n for p, n in extracted_by_inst[name].pins}
+        matched = set()
+        for sym in sorted(intended_pins):
+            cell = pin_map.get(sym, sym)
+            if cell in extracted_pins:
+                matched.add(cell)
+                mapped.append(
+                    (name, sym, cell, intended_pins[sym], extracted_pins[cell])
+                )
+                continue
+            conn = intended_structs.connectivity
+            net_id = intended_pins[sym]
+            findings.append(
+                {
+                    "rule": RULE_UNMAPPED,
+                    "severity": "error",
+                    "message": (
+                        f"pin {name}.{sym} has no extracted counterpart "
+                        f"(cell pin {cell})"
+                    ),
+                    "view": "intended",
+                    "kind": "pin",
+                    "instance": name,
+                    "pin": sym,
+                    "cell_pin": cell,
+                    "side": "intended",
+                    "net": conn.net_name(net_id),
+                    "net_id": net_id,
+                }
+            )
+        for cell in sorted(set(extracted_pins) - matched):
+            conn = extracted_structs.connectivity
+            net_id = extracted_pins[cell]
+            findings.append(
+                {
+                    "rule": RULE_UNMAPPED,
+                    "severity": "error",
+                    "message": (
+                        f"pin {name}.{cell} has no intended counterpart "
+                        f"(symbol pin {back_map.get(cell, cell)})"
+                    ),
+                    "view": "extracted",
+                    "kind": "pin",
+                    "instance": name,
+                    "pin": cell,
+                    "sym_pin": back_map.get(cell, cell),
+                    "side": "extracted",
+                    "net": conn.net_name(net_id),
+                    "net_id": net_id,
+                }
+            )
+    return mapped, findings
+
+
+def _connection_findings(intended_structs, extracted_structs, mapped):
+    """Split (missing) and joined (unexpected) net findings."""
+    findings = []
+    iconn = intended_structs.connectivity
+    econn = extracted_structs.connectivity
+    by_intended = {}
+    for inst, sym, cell, intended_id, extracted_id in mapped:
+        by_intended.setdefault(intended_id, []).append(
+            (inst, sym, cell, extracted_id)
+        )
+    for intended_id in sorted(by_intended):
+        members = by_intended[intended_id]
+        landed = sorted({extracted_id for (_, _, _, extracted_id) in members})
+        if len(landed) > 1:
+            split = [{"net": econn.net_name(x), "net_id": x} for x in landed]
+            pin_list = sorted(f"{i}.{s}" for (i, s, _, _) in members)
+            findings.append(
+                {
+                    "rule": RULE_MISSING_CONNECTION,
+                    "severity": "error",
+                    "message": (
+                        f"net {iconn.net_name(intended_id)} splits across "
+                        f"{', '.join(s['net'] for s in split)} in extracted: "
+                        + ", ".join(pin_list)
+                    ),
+                    "view": "intended",
+                    "net": iconn.net_name(intended_id),
+                    "net_id": intended_id,
+                    "split_across": split,
+                    "members": [
+                        {"instance": i, "pin": s, "cell_pin": c}
+                        for (i, s, c, _) in sorted(members)
+                    ],
+                }
+            )
+    by_extracted = {}
+    for inst, sym, cell, intended_id, extracted_id in mapped:
+        by_extracted.setdefault(extracted_id, []).append(
+            (inst, sym, cell, intended_id)
+        )
+    for extracted_id in sorted(by_extracted):
+        members = by_extracted[extracted_id]
+        sources = sorted({intended_id for (_, _, _, intended_id) in members})
+        if len(sources) > 1:
+            merged = [{"net": iconn.net_name(i), "net_id": i} for i in sources]
+            pin_list = sorted(f"{i}.{c}" for (i, _, c, _) in members)
+            findings.append(
+                {
+                    "rule": RULE_UNEXPECTED_CONNECTION,
+                    "severity": "error",
+                    "message": (
+                        f"net {econn.net_name(extracted_id)} joins "
+                        f"{', '.join(m['net'] for m in merged)} in extracted: "
+                        + ", ".join(pin_list)
+                    ),
+                    "view": "extracted",
+                    "net": econn.net_name(extracted_id),
+                    "net_id": extracted_id,
+                    "merged_from": merged,
+                    "members": [
+                        {"instance": i, "pin": c, "sym_pin": s}
+                        for (i, s, c, _) in sorted(members)
+                    ],
+                }
+            )
+    return findings
+
+
+def _coverage(intended_structs, extracted_structs, mapped, count):
+    """Coverage mapping with the explicit sync statement."""
+    pinless = sum(1 for n in intended_structs.connectivity.nets if not n.pins)
+    pinless += sum(1 for n in extracted_structs.connectivity.nets if not n.pins)
+    intended_nets = len(intended_structs.connectivity.nets)
+    extracted_nets = len(extracted_structs.connectivity.nets)
+    sizes = (
+        f"{intended_nets} vs {extracted_nets} nets, {len(mapped)} mapped pins"
+    )
+    if count == 0:
+        statement = (
+            "view_sync: intended and extracted are in sync "
+            f"(0 findings, {sizes})"
+        )
+    else:
+        noun = "finding" if count == 1 else "findings"
+        statement = (
+            f"view_sync: {count} {noun}; intended vs extracted out of sync "
+            f"({sizes})"
+        )
+    return {
+        "compared_views": ["intended", "extracted"],
+        "intended_nets": intended_nets,
+        "extracted_nets": extracted_nets,
+        "mapped_pins": len(mapped),
+        "pinless_nets_skipped": pinless,
+        "statement": statement,
+    }
+
+
+def compare_views(intended, extracted, links=None, variant=None):
+    """Diff intended vs extracted schematics over shared connectivity.
+
+    Both views reduce through CONNECT-GRAPH extraction, pins
+    correlate through CellLink identity, and ports, connections,
+    and unmapped objects diff with per-finding identity
+    references; every net name resolves through the cited view's
+    `Connectivity.net_name` authority.
+
+    Args:
+        intended: Intended-view schematic record (symbol-pin space;
+            see workflows.connectgraph for the shape).
+        extracted: Extracted-view schematic record (cell-pin space).
+        links: CellLink block links ([{id, CellLink?}]) mapping
+            intended symbol pins to extracted cell pins; None or []
+            correlates by identity.
+        variant: Variant selector applied to every link; None and
+            REFERENCE resolve each stored base link.
+
+    Returns:
+        Mapping with findings (sorted by rule, deterministic),
+            coverage (compared views, net counts, mapped pins,
+            pinless skips, statement), and a text report.
+
+    Raises:
+        ViewSyncError: Malformed schematic (naming its side),
+            malformed links, an unknown variant, or a pinMap
+            collision.
+
+    Caution: Optical view comparison, never transistor LVS —
+        findings judge connectivity sync only, not device
+        equivalence.
+    """
+    forward, reverse = _identity_maps(links, variant)
+    intended_structs = _extract_side(intended, "intended")
+    extracted_structs = _extract_side(extracted, "extracted")
+    mapped, unmapped = _correlate(
+        intended_structs, extracted_structs, forward, reverse
+    )
+    findings = _port_findings(intended_structs, extracted_structs)
+    findings.extend(unmapped)
+    findings.extend(_connection_findings(intended_structs, extracted_structs, mapped))
+    findings.sort(key=lambda f: (f["rule"], json.dumps(f, sort_keys=True)))
+    coverage = _coverage(intended_structs, extracted_structs, mapped, len(findings))
+    lines = [coverage["statement"]]
+    lines.extend(f"- [{f['rule']}] {f['message']}" for f in findings)
+    return {"findings": findings, "coverage": coverage, "report": "\n".join(lines)}

rocket_engine-0.0.2b1.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: rocket-engine
+Version: 0.0.2b1
+Summary: Shared tooling engine used by the RocketEDA IDE (manual actions and MCP invoke the same operations).
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.12
+Requires-Dist: amaranth>=0.5.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: cace==2.13.0
+Requires-Dist: circulax
+Requires-Dist: cocotb>=1.9
+Requires-Dist: devsim==2.11.2
+Requires-Dist: fastapi>=0.115
+Requires-Dist: gdsfactory<10,>=9.51
+Requires-Dist: gplugins<3,>=2.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: mcp<3,>=1.0
+Requires-Dist: meow-sim>=0.15
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyslang>=12.1.0
+Requires-Dist: pyspice>=1.5
+Requires-Dist: pywellen>=0.25.7
+Requires-Dist: pyyaml>=6
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: sax>=0.18
+Requires-Dist: scikit-rf>=1.0
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: vlsirtools>=7.0.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src=".github/assets/rocketide-logo.svg" width="72" height="72" alt="RocketIDE logo">
+</p>
+
+<h1 align="center">rocket-engine</h1>
+
+<p align="center"><sub>Part of <a href="https://github.com/Team-RocketEDA/RocketIDE"><b>RocketIDE</b></a> · the engine</sub></p>
+
+`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](../PRD/README.md). The agent harness is in [rocket_fuel](../rocket_fuel/README.md), the current workbench is in [UIUX](../UIUX/README.md), and [RocketIDE](../RocketIDE/README.md) is the planned packaging layer.
+
+## Requirements
+
+<!-- REQUIREMENTS:START -->
+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)
+
+| Capability | Provides | How to get it |
+|---|---|---|
+| Digital bundle (oss-cad-suite) | `iverilog`, `vvp`, `verilator`, `slang`, `yosys`, `ghdl`, `sby` | scripts/provision_toolchain.sh: pinned tarball 20261025 + asserts (PROV phase 1). |
+| LibreLane (RTL-to-GDS flow) | `librelane` | scripts/provision_toolchain.sh (PROV phase 1; upstream AppImage/Nix install docs). |
+| OpenSTA (static timing) | `sta` | scripts/provision_toolchain.sh (PROV phase 1; upstream OpenSTA README source build). |
+| ngspice (SPICE) | `ngspice` | docs/provision-plan.md: apt pin or source build (B10). |
+| Netgen (LVS) | `netgen` | docs/tickets/NGSPICE-LIVE.md: opencircuitdesign source build (B10). |
+| Magic (DRC + extraction) | `magic` | docs/provision-plan.md: source build with --prefix into the app-owned tools dir (B10). |
+| KLayout (batch DRC) | `klayout` | docs/provision-plan.md: ambient install kept and version-asserted (B10). |
+| Xyce (parallel SPICE) | `Xyce` | scripts/provision_toolchain.sh (PROV phase 2; Xyce building guide recipe). |
+| Xschem (schematic) | `xschem` | scripts/provision_toolchain.sh (PROV phase 2; upstream xschem source build). |
+| Bubblewrap (isolation) | `bwrap` | docs/probe-bwrap-isolation.md (B10). |
+| cvc (SMT solvers) | `cvc4`, `cvc5` | scripts/provision_toolchain.sh: pinned tarball 20261025 ships cvc4/cvc5 (PROV phase 1). |
+| OpenROAD | `openroad` | scripts/provision_toolchain.sh (PROV phase 1; LibreLane closure ships openroad). |
+| openEMS (EC-FDTD) | `openEMS` | scripts/provision_toolchain.sh (PROV-DEFERRED; docs.openEMS.de recipe). |
+| Elmer (thermal/FEM) | `ElmerSolver` | scripts/provision_toolchain.sh (PROV-DEFERRED; CSC PPA apt route). |
+| Palace (full-wave FEM) | `palace` | docs/provision-sources.md §12 (unsourced — no recipe yet). |
+
+### Python libraries (ride the wheel)
+
+| Capability | Provides | How to get it |
+|---|---|---|
+| CACE (characterization) | `cace` | scripts/provision_toolchain.sh (PROV phase 2; pip into the engine venv). |
+| SAX (photonic sim) | `sax` | pyproject.toml [project] dependencies: plain `uv sync` installs everything (core library). |
+| Circulax (time-domain circuit sim) | `circulax` | pyproject.toml [project] dependencies: plain `uv sync` installs everything (core library). |
+| Meow (EME mode/field solver) | `meow` | pyproject.toml [project] dependencies: plain `uv sync` installs everything (core library). |
+| gdsfactory (layout views) | `gdsfactory` | pyproject.toml [project] dependencies: plain `uv sync` installs everything (core library). |
+| pymeep (FDTD) | `meep` | scripts/provision_toolchain.sh (PROV-DEFERRED; conda-forge pymeep env). |
+| DEVSIM (TCAD) | `devsim` | scripts/provision_toolchain.sh (PROV-DEFERRED; pip into the engine venv). |
+
+### PDKs (registered trees, never in the wheel)
+
+| Capability | Provides | How to get it |
+|---|---|---|
+| PDK sky130A | `sky130A` + 4 decks | scripts/install.sh --pdk-only (PDK_SOURCE/PDK_ID/PDK_REVISION; see docs/demo-runbook.md). |
+| PDK ihp (IHP SG13G2 BiCMOS + RF) | `ihp` + 1 decks | docs/pdk/ihp/recipe.md (PDK-IHP lane). |
+
+### Cloud (opt-in only, never default)
+
+| Capability | Provides | How to get it |
+|---|---|---|
+| Tidy3D web (cloud) | BYOC: tidy3d web | CLOUD-AUTH (Backlog): OS keyring preferred, encrypted file fallback. |
+| GDSFactory+ (cloud) | BYOC: gdsfactory+ | CLOUD-AUTH (Backlog): OS keyring preferred, encrypted file fallback. |
+<!-- REQUIREMENTS:END -->
+
+## 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
+
+```text
+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.
+
+| Module | Responsibility |
+|---|---|
+| [`src/interfaces/`](src/interfaces/README.md) | Operation/query vocabulary, contracts, ports, path and design-data types |
+| [`src/project/`](src/project/README.md) | Revision-gated documents, ECS components, snapshots, and event ledger |
+| [`src/execution/`](src/execution/README.md) | Run lifecycle, bounded dispatch, isolation, Python execution approvals, and verdicts |
+| [`src/library/`](src/library/README.md) | PDK registration/readiness and reusable cell catalogs |
+| [`src/workflows/`](src/workflows/README.md) | Digital, analog, photonic, and mixed-domain stage plans and completion checks |
+| [`src/adapters/`](src/adapters/README.md) | CLI, MCP, HTTP/IPC envelope handlers, and solver integrations |
+
+## Registered solver operations
+
+| Operations | Adapter(s) |
+|---|---|
+| `run_drc` | Magic (default), KLayout |
+| `run_hdl_test`, `run_syntax`, `run_formal`, `run_synth`, `run_timing` | Icarus, Slang, SBY, Yosys, OpenSTA |
+| `run_spice`, `run_post_layout`, `run_cosim` | ngspice; co-simulation also uses Icarus |
+| `run_optical`, `run_em` | SAX/Circulax, MEOW |
+| `run_extraction`, `run_lvs` | Magic, Netgen |
+| `run_connectivity`, `run_erc`, `run_view_sync` | connectgraph |
+| `generate_views` | GDSFactory |
+| `run_digital_flow` | LibreLane |
+
+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](docs/work/DIGITAL-FLOW/report.md) and the [sprint board](docs/sprint-board.md) for current work status.
+
+## API contract
+
+**Next implementation contract:** the [v1 contract bundle](contracts/README.md)
+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](docs/adr/014-contract-first-editor-and-tool-api.md) 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`](src/interfaces/vocabulary.py). Handler docstrings are the source for the generated [`docs/engine-api.md`](docs/engine-api.md), [`docs/api-schema.json`](docs/api-schema.json), and [`docs/api-help.json`](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](docs/tickets/MCP-SCHEMA.md).
+
+## 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.
+
+```sh
+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`](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`](AGENTS.md). It also documents the test and fixture workflow. The [scenario guide](scenarios/README.md) describes live-tool prerequisites and the scenario CLI.
+
+## Where to look next
+
+- Project requirements and decisions: [`../PRD/README.md`](../PRD/README.md)
+- Current engine work and open tickets: [`docs/sprint-board.md`](docs/sprint-board.md), [`docs/tickets/`](docs/tickets/)
+- Fuel integration contract: [`docs/fuel-contract.md`](docs/fuel-contract.md)
+- Generated engine API: [`docs/engine-api.md`](docs/engine-api.md)
+- Storage ownership: [`docs/storage-policy.md`](docs/storage-policy.md) and [`docs/adr/`](docs/adr/README.md)