diff --git a/.github/workflows/gcd-reference-verify.yml b/.github/workflows/gcd-reference-verify.yml index 08a34ee..21f7a70 100644 --- a/.github/workflows/gcd-reference-verify.yml +++ b/.github/workflows/gcd-reference-verify.yml @@ -65,7 +65,7 @@ jobs: cache=$(python -c 'import json; print(json.load(open("toolchain.json"))["openroad"]["cache"])') bash tools/install-cached-package.sh openroad "$openroad" "$cache" .cache/gcd-tools echo "$PWD/.cache/gcd-tools/openroad/bin" >> "$GITHUB_PATH" - - name: Install native Python wheels and pinned pure-Python Kepler MCP package + - name: Install native Python wheels, pinned Kepler MCP package and the separate Naja-Scope environment run: | mkdir -p .cache/agent-config-codex .cache/agent-config-claude python setup/mcp.py configure --client codex --project .cache/agent-config-codex \ @@ -73,6 +73,7 @@ jobs: python setup/mcp.py configure --client claude-code --project .cache/agent-config-claude \ --venv .cache/gcd-python --apply | tee .cache/gcd-tools/setup-claude.log .cache/gcd-python/bin/python -m pip freeze > .cache/gcd-tools/python-packages.txt + .cache/gcd-python-scope/bin/python -m pip freeze > .cache/gcd-tools/naja-scope-packages.txt echo "$PWD/.cache/gcd-python/bin" >> "$GITHUB_PATH" - name: Agent MCP discovery and direct live-session verification run: | diff --git a/.gitignore b/.gitignore index 6fd234c..54e5e4b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ __pycache__/ *.py[cod] .DS_Store .venv/ +.venv-scope/ .cache/ runs/ result diff --git a/examples/backend/gcd/reference/README.md b/examples/backend/gcd/reference/README.md index 5b044da..2f8354f 100644 --- a/examples/backend/gcd/reference/README.md +++ b/examples/backend/gcd/reference/README.md @@ -50,7 +50,8 @@ and [package guides](../../../../tools/README.md), not the model task. Follow [tool installation](../../../../tools/README.md). Use the same OpenROAD package for both runs. The prior demo used the Docker image recorded in `toolchain.json`; do not substitute those historical measurements for a new run. -The shared Python environment pins Kepler Formal, NajaEDA and both MCP servers. +The editing environment pins Kepler Formal, NajaEDA and the Kepler MCP server; +Naja-Scope runs from its own pinned environment. From the repository root, in the Python environment with NajaEDA installed: diff --git a/scripts/gcd_reference_regression.py b/scripts/gcd_reference_regression.py index 9080f4f..5e789d9 100644 --- a/scripts/gcd_reference_regression.py +++ b/scripts/gcd_reference_regression.py @@ -45,6 +45,38 @@ def clean_env(): return env +def scope_python(): + """Interpreter of the Naja-Scope environment, which has its own NajaEDA. + + Naja-Scope only ever runs as a separate MCP server that loads files, so it + is installed beside this environment: `-scope`, or NAJA_SCOPE_PYTHON. + """ + override = os.environ.get("NAJA_SCOPE_PYTHON") + prefix = Path(sys.prefix) + # Keep the venv's own executable path: resolving the symlink would leave it. + python = Path(override).expanduser().absolute() if override else ( + prefix.with_name(prefix.name + "-scope") + / ("Scripts/python.exe" if os.name == "nt" else "bin/python")) + if not python.is_file(): + raise ValueError(f"Naja-Scope environment not found at {python}; " + "see tools/naja-scope/install.md") + return python + + +def scope_identity(python, pins): + """Check the Naja-Scope pins in the environment its server runs from.""" + code = ("import importlib.metadata as m, json, sys; " + "print(json.dumps({name: m.version(name) for name in sys.argv[1:]}))") + reply = subprocess.run([str(python), "-I", "-c", code, *pins], env=clean_env(), + stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=60) + if reply.returncode != 0: + raise ValueError("Naja-Scope environment is not usable: " + reply.stderr.strip()[-300:]) + versions = json.loads(reply.stdout) + if versions != pins: + raise ValueError(f"Naja-Scope packages do not match toolchain.json: {versions}") + return versions + + def run_command(directory, command, *, timeout, env=None, accept_nonzero=False): directory.mkdir() save(directory / "command.json", {"argv": [str(x) for x in command], "cwd": str(directory)}) @@ -129,6 +161,10 @@ def scope_payload(result): value = result.structuredContent if value is None: value = json.loads(next(c.text for c in result.content if c.type == "text")) + # Naja-Scope 0.1.25+ publishes structured output, which the MCP SDK wraps + # as {"result": payload}; earlier releases return the payload itself. + if isinstance(value, dict) and set(value) == {"result"} and isinstance(value["result"], dict): + value = value["result"] if not isinstance(value, dict) or "error" in value: raise ValueError(f"Naja-Scope error: {value}") return value @@ -145,12 +181,12 @@ def validate_scope_query(name, value): raise ValueError(f"Naja-Scope returned no {kind} for the reference boundary") -async def inspect_scope(directory, design, liberty): +async def inspect_scope(directory, design, liberty, python): from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client directory.mkdir() - params = StdioServerParameters(command=sys.executable, + params = StdioServerParameters(command=str(python), args=["-m", "naja_scope.server"], env=clean_env()) with (directory / "server.log").open("w") as log: async with stdio_client(params, errlog=log) as streams: @@ -179,6 +215,7 @@ def input_hashes(): return {str(path.relative_to(ROOT)): digest(path) for path in (EXAMPLE / "input.v", EXAMPLE / "constraints.sdc", REFERENCE / "edit.py", PLATFORM / "run.tcl", ROOT / "toolchain.json", ROOT / "tools/python-requirements.txt", + ROOT / "tools/naja-scope/requirements.txt", ROOT / "tools/kepler-formal/verify.py", ROOT / "tools/kepler-formal/mcp-requirements.txt")} @@ -194,6 +231,8 @@ def prepare(work, fixture): run_command(work / "openroad-version", [tools["openroad"], "-version"], timeout=30) version = (work / "openroad-version/tool.log").read_text() require_openroad_revision(version, pins["openroad"]["source_revision"]) + tools["naja_scope_python"] = str(scope_python()) + scope_packages = scope_identity(tools["naja_scope_python"], pins["naja_scope_packages"]) save(work / "kepler-packages.json", SEC.package_identity()) spec = importlib.util.spec_from_file_location("gcd_fixture", PLATFORM / "fetch_fixture.py") module = importlib.util.module_from_spec(spec) @@ -210,7 +249,7 @@ def prepare(work, fixture): "fixture_manifest_sha256": digest(fixture / "manifest.json"), "tools": tools, "openroad_version": version.strip(), "python": sys.version, "python_packages": packages, - "toolchain": pins} + "naja_scope_packages": scope_packages, "toolchain": pins} save(work / "metadata.json", metadata) return metadata @@ -255,7 +294,9 @@ def stage(name, work, fixture, timeout): timeout=timeout, env=env) save(directory / "summary.json", physical_summary(directory)) elif name == "inspect": - asyncio.run(asyncio.wait_for(inspect_scope(directory, design, liberty), timeout=timeout)) + asyncio.run(asyncio.wait_for( + inspect_scope(directory, design, liberty, metadata["tools"]["naja_scope_python"]), + timeout=timeout)) elif name == "edit": ast.parse((REFERENCE / "edit.py").read_text()) run_command(directory, [sys.executable, str(REFERENCE / "edit.py"), "--liberty", str(liberty), diff --git a/scripts/live_inspection_regression.py b/scripts/live_inspection_regression.py index 355ceb0..dbd838f 100644 --- a/scripts/live_inspection_regression.py +++ b/scripts/live_inspection_regression.py @@ -9,7 +9,7 @@ ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT)) -from scripts.gcd_reference_regression import clean_env, save, scope_payload +from scripts.gcd_reference_regression import clean_env, save, scope_payload, scope_python from scripts.live_session_regression import LIBERTY, FIRST, SECOND from tools.live_session import LiveDesignSession @@ -22,7 +22,8 @@ async def run(work): source, library = work / "input.v", work / "cells.lib" source.write_text("module top(input a, output y); BUF g(.A(a), .Y(y)); endmodule\n") library.write_text(LIBERTY) - params = StdioServerParameters(command=sys.executable, args=["-m", "naja_scope.server"], + # Scope reads the exported files from its own environment, not from this kernel's. + params = StdioServerParameters(command=str(scope_python()), args=["-m", "naja_scope.server"], env=clean_env(), cwd=str(ROOT)) with LiveDesignSession(source, [library], work / "session") as live: assert live.verify()["status"] == "proved" diff --git a/setup/README.md b/setup/README.md index 7983991..196cf2b 100644 --- a/setup/README.md +++ b/setup/README.md @@ -19,7 +19,10 @@ python3.13 setup/mcp.py configure --client claude-code --apply The same installer checks and reuses `.venv`, installs only missing/mismatched pins, tests real MCP initialization, lists tools and calls Kepler's native -information tool, then writes the selected client's **project-local** config: +information tool, then writes the selected client's **project-local** config. +It also creates or reuses `.venv-scope`, the separate +[Naja-Scope environment](../tools/naja-scope/install.md); registering the +Naja-Scope server with the agent remains a manual step described there. | Client | Generated file | Activation | | --- | --- | --- | @@ -27,7 +30,9 @@ information tool, then writes the selected client's **project-local** config: | Claude Code | `.mcp.json` | Approve the project MCP server, reload, check `/mcp` | Use `--venv /absolute/existing-venv` to reuse the kernel's environment, and -`--project /absolute/project` to configure a different project. An existing venv +`--project /absolute/project` to configure a different project. The Naja-Scope +environment defaults to that venv's path plus `-scope`; `--scope-venv` selects +another one. An existing venv is modified only with `--apply`; use a dedicated one if its other packages must remain unchanged. Config entries use absolute paths to that interpreter and this checkout's launcher, so keep both at those paths. Regenerate after moving. @@ -41,6 +46,7 @@ The standard generated files are ignored by this repository. The installer uses [pinned native wheels](../tools/python-requirements.txt), [kernel packages](../tools/session-requirements.txt) and the [pinned pure-Python wrapper](../tools/kepler-formal/mcp-requirements.txt). +The Naja-Scope environment gets only [its own pins](../tools/naja-scope/requirements.txt). No Nix, native build or source submodule is needed for this MCP. Missing native wheels are an error, not permission to compile. The launcher checks the package pins on every startup. Transitive dependencies are not fully locked. @@ -51,7 +57,8 @@ Check an existing installation without installing or changing configuration: python3.13 setup/mcp.py check --venv .venv ``` -This checks transport/tool discovery and native loading, **not** whether your +This checks transport/tool discovery and native loading, and that the +Naja-Scope environment matches its pins, **not** whether your agent has approved or displayed the tools, and not circuit equivalence. In the agent's tool list confirm `get_kepler_formal_info`, `attach_session`, `verify_session` and `get_session_reports`. Existing user/admin settings can diff --git a/setup/mcp.py b/setup/mcp.py index 851692d..658d2fd 100644 --- a/setup/mcp.py +++ b/setup/mcp.py @@ -64,13 +64,18 @@ def python_in(directory): return directory / ("Scripts/python.exe" if os.name == "nt" else "bin/python") -def install(directory): +def ensure_venv(directory, option): python = python_in(directory) if directory.exists(): if not (directory / "pyvenv.cfg").is_file() or not python.is_file(): - raise ValueError("Existing environment is not a usable venv; choose another --venv") + raise ValueError(f"Existing environment is not a usable venv; choose another {option}") else: venv.EnvBuilder(with_pip=True).create(directory) + return python + + +def install(directory): + python = ensure_venv(directory, "--venv") state = json.loads(run([python, "-I", SCRIPT, "identity"], capture=True).stdout) if not state["packages_match"]: run([python, "-I", "-m", "pip", "install", "--only-binary=:all:", @@ -85,6 +90,50 @@ def install(directory): return python +def scope_directory(directory): + """Naja-Scope's own venv, beside Kepler's: it needs a newer NajaEDA than Kepler pins.""" + return directory.with_name(directory.name + "-scope") + + +def scope_state(python): + """Compare the Naja-Scope pins with what its environment has installed.""" + pins = json.loads((ROOT / "toolchain.json").read_text())["naja_scope_packages"] + code = ("import importlib.metadata as m, json, sys\n" + "def version(name):\n" + " try:\n" + " return m.version(name)\n" + " except m.PackageNotFoundError:\n" + " return None\n" + "print(json.dumps({name: version(name) for name in sys.argv[1:]}))") + versions = json.loads(run([python, "-I", "-c", code, *pins], capture=True).stdout) + return {"packages_match": versions == pins, "versions": versions} + + +def install_scope(directory): + """Create or reuse the Naja-Scope environment, kept separate from Kepler's.""" + python = ensure_venv(directory, "--scope-venv") + if scope_state(python)["packages_match"]: + print("Reusing the matching Naja-Scope installation.", flush=True) + else: + run([python, "-I", "-m", "pip", "install", "--only-binary=:all:", + "-r", ROOT / "tools/naja-scope/requirements.txt"]) + run([python, "-I", "-m", "pip", "check"]) + return python + + +def check_scope(directory): + """Read-only: the Naja-Scope server interpreter exists and matches its pins.""" + python = python_in(directory) + if not python.is_file(): + raise ValueError(f"Naja-Scope environment not found: {directory}") + state = scope_state(python) + if not state["packages_match"]: + raise ValueError(f"Naja-Scope environment does not match the toolchain pins: {state['versions']}") + result = {"naja_scope": "ready", "python": str(python), "packages": state["versions"]} + print(json.dumps(result, indent=2), flush=True) + return result + + def configuration(client, python): config = {"command": str(python), "args": ["-I", str(LAUNCHER)]} if client == "codex": @@ -200,6 +249,8 @@ def main(argv=None): parser.add_argument("--client", choices=("codex", "claude-code")) parser.add_argument("--project", type=Path, default=ROOT) parser.add_argument("--venv", type=Path, help="Existing/new dedicated venv (default: PROJECT/.venv)") + parser.add_argument("--scope-venv", type=Path, + help="Existing/new Naja-Scope venv (default: the --venv path plus -scope)") parser.add_argument("--name", default="kepler-formal") parser.add_argument("--apply", action="store_true", help="Install and write project config; otherwise preview only") args = parser.parse_args(argv) @@ -211,9 +262,11 @@ def main(argv=None): return project = args.project.resolve(strict=True) directory = args.venv.resolve() if args.venv else project / ".venv" + scope = args.scope_venv.resolve() if args.scope_venv else scope_directory(directory) python = python_in(directory) if args.action == "check": check(python) + check_scope(scope) return if not args.client: parser.error("configure requires --client") @@ -224,12 +277,13 @@ def main(argv=None): old = read_config(path) new = render_config(old, args.client, args.name, entry) print(json.dumps({"client": args.client, "scope": "project", "config": str(path), - "environment": str(directory), "server": entry, - "apply": args.apply}, indent=2), flush=True) + "environment": str(directory), "naja_scope_environment": str(scope), + "server": entry, "apply": args.apply}, indent=2), flush=True) if not args.apply: print("Preview only. Add --apply to install, test MCP discovery, and register.") return install(directory) + install_scope(scope) check(python) write_config(path, old, new) print("Registered. Reload the agent and approve the trusted project/server. " diff --git a/tests/test_gcd_reference_regression.py b/tests/test_gcd_reference_regression.py index fe64fc7..1cbfc34 100644 --- a/tests/test_gcd_reference_regression.py +++ b/tests/test_gcd_reference_regression.py @@ -75,6 +75,66 @@ def version_run(directory, command, **kwargs): REPLAY.prepare(self.work / "new", self.work / "fixture") fetch_loader.assert_not_called() + def test_prepare_rejects_wrong_scope_environment_before_downloading_fixture(self): + pins = json.loads((ROOT / "toolchain.json").read_text()) + revision = pins["openroad"]["source_revision"] + + def version_run(directory, command, **kwargs): + directory.mkdir() + (directory / "tool.log").write_text(f"2.0_{revision}\n") + + with patch.object(REPLAY.importlib.metadata, "version", side_effect=pins["python_packages"].get), \ + patch.object(REPLAY.shutil, "which", return_value="/tools/openroad"), \ + patch.object(REPLAY, "run_command", side_effect=version_run), \ + patch.object(REPLAY, "scope_python", return_value=Path("/scope/bin/python")), \ + patch.object(REPLAY.subprocess, "run", return_value=subprocess.CompletedProcess( + [], 0, json.dumps(dict(pins["naja_scope_packages"], najaeda="0.0.0")), "")) as run, \ + patch.object(REPLAY.importlib.util, "spec_from_file_location") as fetch_loader: + with self.assertRaisesRegex(ValueError, "Naja-Scope packages do not match"): + REPLAY.prepare(self.work / "new", self.work / "fixture") + # The pins are read in the Scope interpreter, never in this one. + self.assertEqual(run.call_args.args[0][0], "/scope/bin/python") + self.assertEqual(run.call_args.args[0][-len(pins["naja_scope_packages"]):], + list(pins["naja_scope_packages"])) + fetch_loader.assert_not_called() + + def test_scope_identity_accepts_only_the_pinned_environment(self): + pins = {"naja-scope": "1.2.3", "najaeda": "4.5.6"} + for code, stdout, message in ((0, json.dumps(pins), None), + (0, json.dumps(dict(pins, najaeda="4.5.7")), "do not match"), + (1, "", "not usable")): + reply = subprocess.CompletedProcess([], code, stdout, "No package metadata was found") + with self.subTest(code=code, stdout=stdout), patch.object(REPLAY.subprocess, "run", return_value=reply): + if message is None: + self.assertEqual(REPLAY.scope_identity("/scope/python", pins), pins) + else: + with self.assertRaisesRegex(ValueError, message): + REPLAY.scope_identity("/scope/python", pins) + + def test_scope_interpreter_is_beside_the_editing_venv_or_explicit(self): + executable = "Scripts/python.exe" if REPLAY.os.name == "nt" else "bin/python" + beside = self.work / "env-scope" / executable + explicit = self.work / "elsewhere" / executable + setup_spec = importlib.util.spec_from_file_location("mcp_setup", ROOT / "setup/mcp.py") + setup = importlib.util.module_from_spec(setup_spec) + setup_spec.loader.exec_module(setup) + # The installer creates the environment where the regressions look for it. + self.assertEqual(setup.python_in(setup.scope_directory(self.work / "env")), beside) + with patch.object(REPLAY.sys, "prefix", str(self.work / "env")), \ + patch.dict(REPLAY.os.environ, clear=False) as environment: + environment.pop("NAJA_SCOPE_PYTHON", None) + with self.assertRaisesRegex(ValueError, "tools/naja-scope/install.md"): + REPLAY.scope_python() + for path in (beside, explicit): + path.parent.mkdir(parents=True) + path.touch() + self.assertEqual(REPLAY.scope_python(), beside) + environment["NAJA_SCOPE_PYTHON"] = str(explicit) + self.assertEqual(REPLAY.scope_python(), explicit) + environment["NAJA_SCOPE_PYTHON"] = str(self.work / "missing") + with self.assertRaisesRegex(ValueError, "not found"): + REPLAY.scope_python() + def test_tool_failure_prints_bounded_tail_and_preserves_full_log(self): captured = io.StringIO() command = [sys.executable, "-c", @@ -283,10 +343,22 @@ def test_changed_candidate_after_proof_is_rejected(self): REPLAY.validate_inputs(self.work, metadata) def test_scope_errors_rejected_even_in_successful_mcp_envelopes(self): - for error, value in ((True, {}), (False, {"error": "not found"})): - with self.assertRaises(ValueError): + for error, value in ((True, {}), (False, {"error": "not found"}), + (False, {"result": {"error": "not found"}})): + with self.subTest(value=value), self.assertRaises(ValueError): REPLAY.scope_payload(SimpleNamespace(isError=error, structuredContent=value)) + def test_scope_payload_is_the_same_with_or_without_the_result_wrapper(self): + payload = {"loaded": True, "top": {"name": "gcd"}} + text = SimpleNamespace(type="text", text=json.dumps({"result": payload})) + for response in (SimpleNamespace(isError=False, structuredContent=payload), + SimpleNamespace(isError=False, structuredContent={"result": payload}), + SimpleNamespace(isError=False, structuredContent=None, content=[text])): + self.assertEqual(REPLAY.scope_payload(response), payload) + # A payload that merely has a result field among others is left alone. + mixed = {"result": {"loaded": True}, "count": 1} + self.assertEqual(REPLAY.scope_payload(SimpleNamespace(isError=False, structuredContent=mixed)), mixed) + def test_scope_requires_correct_top_and_complete_boundary_results(self): REPLAY.validate_scope_query("status", {"loaded": True, "top": {"name": "gcd"}}) REPLAY.validate_scope_query("get_loads", {"leaf_loads": [{"path": "gcd.consumer"}]}) diff --git a/tests/test_repository.py b/tests/test_repository.py index 8219df7..4c1b31c 100644 --- a/tests/test_repository.py +++ b/tests/test_repository.py @@ -85,6 +85,12 @@ def test_package_pins_and_no_submodule_manifest(self): requirements = (ROOT / "tools/python-requirements.txt").read_text().splitlines() self.assertEqual(set(requirements), {f"{key}=={value}" for key, value in manifest["python_packages"].items()}) + # Naja-Scope needs a newer NajaEDA than Kepler's exact pin: separate environments. + scope = manifest["naja_scope_packages"] + self.assertNotIn("naja-scope", manifest["python_packages"]) + self.assertTrue({"naja-scope", "najaeda"} <= set(scope)) + self.assertEqual(set((ROOT / "tools/naja-scope/requirements.txt").read_text().splitlines()), + {f"{key}=={value}" for key, value in scope.items()}) if __name__ == "__main__": diff --git a/tests/test_setup_mcp.py b/tests/test_setup_mcp.py index 8520d4f..a9294ae 100644 --- a/tests/test_setup_mcp.py +++ b/tests/test_setup_mcp.py @@ -60,14 +60,17 @@ def test_malformed_configs_fail(self): setup.render_config(data, client, "test", {}) def test_config_preview_does_not_install_or_write(self): - with patch.object(setup, "install") as install, patch.object(setup, "check") as check: + with patch.object(setup, "install") as install, patch.object(setup, "check") as check, \ + patch.object(setup, "install_scope") as install_scope: setup.main(["configure", "--client", "codex", "--project", str(self.project)]) install.assert_not_called() + install_scope.assert_not_called() check.assert_not_called() self.assertEqual(list(self.project.iterdir()), []) def test_apply_checks_before_writing(self): with patch.object(setup, "install", return_value=self.python), \ + patch.object(setup, "install_scope", return_value=self.python), \ patch.object(setup, "check", side_effect=ValueError("discovery failed")): with self.assertRaisesRegex(ValueError, "discovery failed"): setup.main(["configure", "--client", "codex", "--project", str(self.project), "--apply"]) @@ -76,9 +79,59 @@ def test_apply_checks_before_writing(self): def test_conflict_is_checked_before_installation(self): path = self.project / ".mcp.json" path.write_text('{"mcpServers":{"kepler-formal":{"command":"other"}}}') - with patch.object(setup, "install") as install, self.assertRaises(ValueError): + with patch.object(setup, "install") as install, \ + patch.object(setup, "install_scope") as install_scope, self.assertRaises(ValueError): setup.main(["configure", "--client", "claude-code", "--project", str(self.project), "--apply"]) install.assert_not_called() + install_scope.assert_not_called() + + def test_apply_installs_scope_in_its_own_environment(self): + venv = self.project / "env" + for arguments, expected in (([], self.project / "env-scope"), + (["--scope-venv", str(self.project / "other")], self.project / "other")): + with self.subTest(arguments=arguments), \ + patch.object(setup, "install", return_value=self.python) as install, \ + patch.object(setup, "install_scope", return_value=self.python) as install_scope, \ + patch.object(setup, "check"), patch.object(setup, "write_config"): + setup.main(["configure", "--client", "codex", "--project", str(self.project), + "--venv", str(venv), "--apply", *arguments]) + install.assert_called_once_with(venv.resolve()) + install_scope.assert_called_once_with(expected.resolve()) + + def scope_venv(self): + directory = self.project / "venv-scope" + (directory / "bin").mkdir(parents=True) + (directory / "pyvenv.cfg").touch() + (directory / "bin/python").touch() + return directory + + def test_matching_scope_environment_reused_without_pip_install(self): + pins = json.loads((ROOT / "toolchain.json").read_text())["naja_scope_packages"] + result = subprocess.CompletedProcess([], 0, json.dumps(pins)) + with patch.object(setup, "run", return_value=result) as run: + setup.install_scope(self.scope_venv()) + self.assertEqual(len(run.call_args_list), 2) + self.assertEqual(run.call_args_list[0].args[0][-len(pins):], list(pins)) + self.assertEqual(run.call_args_list[-1].args[0][-2:], ["pip", "check"]) + + def test_mismatched_scope_environment_installs_only_its_own_binary_pins(self): + result = subprocess.CompletedProcess([], 0, '{"naja-scope": null, "najaeda": "0.0.0", "mcp": null}') + with patch.object(setup, "run", return_value=result) as run: + setup.install_scope(self.scope_venv()) + command = [str(part) for part in run.call_args_list[1].args[0]] + self.assertIn("--only-binary=:all:", command) + self.assertEqual(Path(command[-1]), ROOT / "tools/naja-scope/requirements.txt") + self.assertFalse([part for part in command if part.endswith(("python-requirements.txt", + "mcp-requirements.txt"))]) + self.assertEqual(run.call_args_list[-1].args[0][-2:], ["pip", "check"]) + + def test_check_rejects_missing_or_mismatched_scope_environment(self): + with self.assertRaisesRegex(ValueError, "not found"): + setup.check_scope(self.project / "absent") + result = subprocess.CompletedProcess([], 0, '{"naja-scope": "0.0.1"}') + with patch.object(setup, "run", return_value=result), \ + self.assertRaisesRegex(ValueError, "does not match"): + setup.check_scope(self.scope_venv()) def test_write_backups_and_noop_does_not_rewrite(self): path = self.project / ".mcp.json" @@ -149,8 +202,10 @@ def test_native_packages_never_fall_back_to_source_builds(self): self.assertIn("--only-binary=:all:", run.call_args_list[1].args[0]) def test_existing_non_venv_untouched(self): - with self.assertRaisesRegex(ValueError, "not a usable venv"): - setup.install(self.project) + for install in (setup.install, setup.install_scope): + with self.subTest(install=install.__name__), \ + self.assertRaisesRegex(ValueError, "not a usable venv"): + install(self.project) def test_launcher_uses_absolute_path_and_keeps_venv_symlink(self): entry = setup.configuration("codex", self.python) diff --git a/toolchain.json b/toolchain.json index 32275e8..6072026 100644 --- a/toolchain.json +++ b/toolchain.json @@ -3,7 +3,7 @@ "nixpkgs": "github:NixOS/nixpkgs/8ce4ef6cb6f871616146b9fe26d2a5ae594e94fe", "kepler_formal_mcp": { "repository": "https://github.com/keplertech/kepler-formal-mcp.git", - "revision": "b66e0ee7ca83635300ab7b602a6ba7611a34c1d6", + "revision": "6bbba137b338f9d140f6080bd255882913dd341d", "version": "0.1.0" }, "openroad": { @@ -17,12 +17,16 @@ }, "python": {"nixpkgs_attribute": "python313"}, "python_packages": { - "najaeda": "0.7.24", - "naja-scope": "0.1.11", - "kepler-formal": "0.5.0", + "najaeda": "0.7.33", + "kepler-formal": "1.0.0", "mcp": "1.30.0", "PyYAML": "6.0.3" }, + "naja_scope_packages": { + "naja-scope": "0.1.26", + "najaeda": "0.7.35", + "mcp": "1.30.0" + }, "gcd": { "fixture_revision": "a9147cf3aebe65e058bb3fa89c1f9e524488dbb8", "historical_openroad_image": "openroad/orfs@sha256:751a77afcade9882b51427e6d9d079b8e270e7a8f4aa66df2d0659457d1c29fd" diff --git a/tools/README.md b/tools/README.md index f17ae85..ebee120 100644 --- a/tools/README.md +++ b/tools/README.md @@ -14,10 +14,13 @@ Package installation and registration with the agent host are separate steps. | Kepler Formal | [Python-backed MCP + native wheels](kepler-formal/install.md) | SEC verification | | OpenROAD | [Nixpkgs package](openroad/install.md) | Physical design and reports | | NajaEDA | [Published Python wheel](najaeda/install.md) | Structural editing | -| Naja-Scope | [Published Python wheel](naja-scope/install.md) | Read-only structural inspection through MCP | +| Naja-Scope | [Published Python wheel, own environment](naja-scope/install.md) | Read-only structural inspection through MCP | -Nix supplies OpenROAD and, optionally, Python. Kepler Formal, NajaEDA and -Naja-Scope use published wheels in a shared project-local virtual environment. +Nix supplies OpenROAD and, optionally, Python. Kepler Formal and NajaEDA use +published wheels in one project-local virtual environment: Kepler verifies +NajaEDA's live objects, so both need the same NajaEDA build. Naja-Scope runs as +a separate file-based MCP server and has its own environment, with the NajaEDA +release it requires. The pure-Python Kepler MCP wrapper is packaged from a pinned Git revision until upstream publishes a distribution. This is not a fully Nix-locked Python environment. No 22b source submodules or native source builds are used. @@ -52,10 +55,14 @@ python -m pip install --only-binary=:all: -r tools/python-requirements.txt python -m pip install --no-deps -r tools/kepler-formal/mcp-requirements.txt python -m pip check python -m pip freeze > .venv/resolved-packages.txt +# Naja-Scope's own environment, beside the first one: +python3 -m venv .venv-scope +.venv-scope/bin/python -m pip install --only-binary=:all: -r tools/naja-scope/requirements.txt +.venv-scope/bin/python -m pip check ``` An existing Python 3.13 interpreter with a compatible wheel can also create the -venv. The requirement pins identify the tool releases, not every transitive +venvs. The requirement pins identify the tool releases, not every transitive dependency; retain the resolved package list with each experiment. Package installation accesses public registries; design files do not need to diff --git a/tools/kepler-formal/install.md b/tools/kepler-formal/install.md index 7e92c6b..3443f7c 100644 --- a/tools/kepler-formal/install.md +++ b/tools/kepler-formal/install.md @@ -4,7 +4,7 @@ to call the `kepler-formal` Python library. It no longer launches the Nix CLI or depends on `keplertech` Cachix for verification. OpenROAD still uses Nix. -Use the [shared Python environment](../README.md). Check existing versions and +Use the [editing environment](../README.md), shared with NajaEDA. Check existing versions and the MCP commit before installing; `kepler-formal-mcp==0.1.0` alone does not distinguish the new Python server from the older CLI wrapper. @@ -26,8 +26,8 @@ For an existing MCP installation at a different Git revision, add Pip may otherwise retain the old revision because both use version `0.1.0`. Reuse an installation whose Git revision already matches the requirement. -The native dependencies are published wheels: `kepler-formal==0.5.0` requires -`najaeda==0.7.24`. Python 3.13 is used by the regression. If a compatible native +The native dependencies are published wheels: `kepler-formal==1.0.0` requires +`najaeda==0.7.33`. Python 3.13 is used by the regression. If a compatible native wheel is unavailable, stop; never compile Kepler or Naja as a fallback. The MCP wrapper has no published PyPI package at this pin. Its separate diff --git a/tools/kepler-formal/mcp-requirements.txt b/tools/kepler-formal/mcp-requirements.txt index c423178..577f156 100644 --- a/tools/kepler-formal/mcp-requirements.txt +++ b/tools/kepler-formal/mcp-requirements.txt @@ -1 +1 @@ -kepler-formal-mcp @ git+https://github.com/keplertech/kepler-formal-mcp.git@b66e0ee7ca83635300ab7b602a6ba7611a34c1d6 +kepler-formal-mcp @ git+https://github.com/keplertech/kepler-formal-mcp.git@6bbba137b338f9d140f6080bd255882913dd341d diff --git a/tools/naja-scope/SKILL.md b/tools/naja-scope/SKILL.md index faf42ad..d2f5fc7 100644 --- a/tools/naja-scope/SKILL.md +++ b/tools/naja-scope/SKILL.md @@ -9,7 +9,8 @@ Use the [package guide](install.md). Discover the installed typed-tool schemas, then load Liberty and Verilog with `load_liberty` and `load_verilog`. Confirm the top and loaded design with `status` before querying. -The pinned MCP server owns a separate loaded copy, not the live editing +The pinned MCP server runs from its own environment, with its own NajaEDA +release, and owns a separate loaded copy, not the live editing candidate. Load original files once for baseline analysis. For a persistent NajaEDA session, use [inspection checkpoints](checkpoints.md): export on demand, record which revision Scope loaded, and check freshness before using its answers diff --git a/tools/naja-scope/checkpoints.md b/tools/naja-scope/checkpoints.md index 68a76e3..9317316 100644 --- a/tools/naja-scope/checkpoints.md +++ b/tools/naja-scope/checkpoints.md @@ -2,7 +2,8 @@ Use this file-based handoff with the pinned Naja-Scope MCP server. Golden, candidate and automatic SEC remain in their existing Python/Jupyter kernel. -Do not import Scope or call its load/reset tools inside that kernel. +Scope is installed in [its own environment](install.md), not in that kernel's: +do not import it or call its load/reset tools there. ## Decide Whether To Refresh @@ -69,7 +70,8 @@ permissions and hashes detect accidents, not hostile same-user Python code. Freshness means the copy came from the current revision and its files are unchanged, **not** that export preserved connectivity. Every manifest says -`export_equivalence: not_checked`. In-memory SEC is not a proof of dumped +`export_equivalence: not_checked`. Scope also parses the export with its own +NajaEDA release, which can differ from the kernel's. In-memory SEC is not a proof of dumped Verilog; if an inspection answer will drive a subsequent edit, confirm its target objects and connections in the live candidate before editing. Exported Verilog used for physical measurements or equivalence claims must pass the diff --git a/tools/naja-scope/install.md b/tools/naja-scope/install.md index 1523f32..d5d4a33 100644 --- a/tools/naja-scope/install.md +++ b/tools/naja-scope/install.md @@ -1,18 +1,26 @@ # Install Naja-Scope -Use the [shared Python environment](../README.md). The pinned pair is -`naja-scope==0.1.11` with `najaeda==0.7.24`; see the -[published scope package](https://pypi.org/project/naja-scope/0.1.11/). +Naja-Scope has its own virtual environment, `.venv-scope`, beside the +[editing environment](../README.md). It runs only as a separate MCP server that +loads files, and its releases require a newer NajaEDA than the exact build +Kepler Formal pins. The [pinned set](requirements.txt) is `naja-scope==0.1.26`, +`najaeda==0.7.35` and `mcp==1.30.0`; see the +[published scope package](https://pypi.org/project/naja-scope/0.1.26/). ```sh -. .venv/bin/activate -python -m pip install --only-binary=:all: 'najaeda==0.7.24' 'naja-scope==0.1.11' -python -m pip check -NAJA_SCOPE_ENABLE_PYTHON=0 naja-scope-mcp +python3 -m venv .venv-scope +.venv-scope/bin/python -m pip install --only-binary=:all: -r tools/naja-scope/requirements.txt +.venv-scope/bin/python -m pip check +NAJA_SCOPE_ENABLE_PYTHON=0 .venv-scope/bin/naja-scope-mcp ``` +[Agent setup](../../setup/README.md) creates the same environment. The +regressions look for it at the editing venv's path plus `-scope`; set +`NAJA_SCOPE_PYTHON` to its interpreter for any other location. Do not install +Naja-Scope into the editing environment or import it in the editing kernel. + The last command starts the stdio MCP server and waits for a client. Configure -your MCP client to launch the venv's absolute `naja-scope-mcp` path with that -environment variable. Do not mistake waiting for stdin for a hung install. +your MCP client to launch that environment's absolute `naja-scope-mcp` path with +that environment variable. Do not mistake waiting for stdin for a hung install. Use typed inspection tools; arbitrary Python execution is not needed for this flow. No unauthenticated network listener is required. diff --git a/tools/naja-scope/requirements.txt b/tools/naja-scope/requirements.txt new file mode 100644 index 0000000..ebfbd1a --- /dev/null +++ b/tools/naja-scope/requirements.txt @@ -0,0 +1,3 @@ +naja-scope==0.1.26 +najaeda==0.7.35 +mcp==1.30.0 diff --git a/tools/najaeda/install.md b/tools/najaeda/install.md index 179c9f9..9fd82dc 100644 --- a/tools/najaeda/install.md +++ b/tools/najaeda/install.md @@ -1,17 +1,19 @@ # Install NajaEDA -Use the [shared Python environment](../README.md) and published binary wheel -`najaeda==0.7.24`, rather than compiling Naja or checking it out as a submodule. -The [published package](https://pypi.org/project/najaeda/0.7.24/) identifies supported +Use the [editing environment](../README.md) and published binary wheel +`najaeda==0.7.33`, rather than compiling Naja or checking it out as a submodule. +The [published package](https://pypi.org/project/najaeda/0.7.33/) identifies supported Python/platform wheels. The initial example uses Python 3.13. ```sh . .venv/bin/activate -python -m pip install --only-binary=:all: 'najaeda==0.7.24' +python -m pip install --only-binary=:all: 'najaeda==0.7.33' python -c 'from importlib.metadata import version; from najaeda import netlist; print(version("najaeda")); print(netlist.__file__)' ``` If no compatible wheel is available, stop and report the platform/Python mismatch; do not fall back to building from source. Do not set paths to an old source build -or mix it with a different Naja version: Kepler Formal 0.5.0 requires this exact -NajaEDA wheel version in the shared environment. +or mix it with a different Naja version: Kepler Formal 1.0.0 requires this exact +NajaEDA wheel version in the editing environment. The separate +[Naja-Scope environment](../naja-scope/install.md) has its own NajaEDA, which is +never used for editing or verification. diff --git a/tools/python-requirements.txt b/tools/python-requirements.txt index 0fe7cfa..1f88841 100644 --- a/tools/python-requirements.txt +++ b/tools/python-requirements.txt @@ -1,5 +1,4 @@ -najaeda==0.7.24 -naja-scope==0.1.11 -kepler-formal==0.5.0 +najaeda==0.7.33 +kepler-formal==1.0.0 mcp==1.30.0 PyYAML==6.0.3