lean-runtime 0.6.0__py3-none-any.whl

lean_runtime/__init__.py

@@ -0,0 +1,67 @@
+"""Content-addressed execution environments for Lean 4."""
+
+from .environments import (
+    Environment,
+    EnvironmentInfo,
+    ExecutionCapture,
+    ExecutionJob,
+    InteractiveSession,
+)
+from .errors import (
+    EnvironmentError,
+    LeanRuntimeError,
+    MaterializationError,
+    PolicyError,
+    ProjectError,
+    ResolutionError,
+    SpecificationError,
+    ToolchainError,
+)
+from .events import EventCallback, RuntimeEvent
+from .health import DoctorCheck, DoctorReport
+from .lockfiles import EnvironmentLock, LockedPackage
+from .models import Diagnostic, ExecutionProvenance, ExecutionResult, PackageProvenance
+from .policies import ExecutionPolicy
+from .references import DiscoveredPackage, PackageReference
+from .runtime import Runtime, project_toolchain
+from .specs import EnvironmentSpec, GitPackage, Package
+from .store import GarbageCollectionReport, StoreStatus
+from .toolchains import ToolchainManager, normalize_toolchain
+
+__all__ = [
+    "Diagnostic",
+    "DiscoveredPackage",
+    "DoctorCheck",
+    "DoctorReport",
+    "Environment",
+    "EnvironmentError",
+    "EnvironmentInfo",
+    "EnvironmentLock",
+    "EnvironmentSpec",
+    "ExecutionCapture",
+    "ExecutionJob",
+    "InteractiveSession",
+    "ExecutionPolicy",
+    "ExecutionProvenance",
+    "ExecutionResult",
+    "EventCallback",
+    "GarbageCollectionReport",
+    "GitPackage",
+    "LeanRuntimeError",
+    "LockedPackage",
+    "MaterializationError",
+    "Package",
+    "PackageReference",
+    "PackageProvenance",
+    "PolicyError",
+    "ProjectError",
+    "ResolutionError",
+    "Runtime",
+    "RuntimeEvent",
+    "SpecificationError",
+    "StoreStatus",
+    "ToolchainError",
+    "ToolchainManager",
+    "normalize_toolchain",
+    "project_toolchain",
+]

lean_runtime/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lean_runtime/backends.py

@@ -0,0 +1,373 @@
+"""Execution backends and the trusted local implementation."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, BinaryIO, Protocol, TextIO, cast
+
+from .errors import PolicyError
+from .policies import ExecutionPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class BackendResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+    elapsed_seconds: float
+    timed_out: bool
+    cancelled: bool
+    output_truncated: bool
+    enforced_policy_fields: tuple[str, ...]
+
+
+class Backend(Protocol):
+    name: str
+
+    def execute(
+        self,
+        command: Sequence[str],
+        *,
+        cwd: Path,
+        environment: Mapping[str, str],
+        policy: ExecutionPolicy,
+        cancel: threading.Event | None = None,
+    ) -> BackendResult: ...
+
+
+class InteractiveTextReader(Protocol):
+    @property
+    def closed(self) -> bool: ...
+
+    def read(self, size: int = -1) -> str: ...
+
+    def readline(self, size: int = -1) -> str: ...
+
+    def fileno(self) -> int: ...
+
+    def close(self) -> None: ...
+
+
+class InteractiveProcess(Protocol):
+    """Live standard-I/O streams plus managed process finalization."""
+
+    stdin: TextIO
+    stdout: InteractiveTextReader
+    stderr: InteractiveTextReader
+
+    def poll(self) -> int | None: ...
+
+    def finish(self) -> BackendResult: ...
+
+
+class _OutputBudget:
+    def __init__(self, limit: int) -> None:
+        self.remaining = limit
+        self.lock = threading.Lock()
+        self.truncated = False
+
+    def take(self, chunk: bytes) -> bytes:
+        with self.lock:
+            size = min(len(chunk), self.remaining)
+            self.remaining -= size
+            if size < len(chunk):
+                self.truncated = True
+            return chunk[:size]
+
+
+def _drain(stream: BinaryIO, budget: _OutputBudget, chunks: list[bytes]) -> None:
+    while True:
+        chunk = stream.read(65_536)
+        if not chunk:
+            return
+        kept = budget.take(chunk)
+        if kept:
+            chunks.append(kept)
+
+
+class _TranscriptReader:
+    """Mirror caller-consumed text into the bounded execution transcript."""
+
+    def __init__(self, stream: TextIO, budget: _OutputBudget, chunks: list[bytes]) -> None:
+        self._stream = stream
+        self._budget = budget
+        self._chunks = chunks
+
+    @property
+    def closed(self) -> bool:
+        return self._stream.closed
+
+    def fileno(self) -> int:
+        return self._stream.fileno()
+
+    def _record(self, value: str) -> str:
+        if value:
+            kept = self._budget.take(value.encode("utf-8"))
+            if kept:
+                self._chunks.append(kept)
+        return value
+
+    def read(self, size: int = -1) -> str:
+        return self._record(self._stream.read(size))
+
+    def readline(self, size: int = -1) -> str:
+        return self._record(self._stream.readline(size))
+
+    def close(self) -> None:
+        self._stream.close()
+
+
+class _LocalInteractiveProcess:
+    def __init__(
+        self,
+        process: subprocess.Popen[str],
+        *,
+        policy: ExecutionPolicy,
+        enforced_policy_fields: tuple[str, ...],
+    ) -> None:
+        assert process.stdin is not None
+        assert process.stdout is not None
+        assert process.stderr is not None
+        self._process = process
+        self._policy = policy
+        self._enforced_policy_fields = enforced_policy_fields
+        self._started = time.monotonic()
+        self._timed_out = threading.Event()
+        self._finished = threading.Event()
+        self._budget = _OutputBudget(policy.max_output_bytes)
+        self._stdout_chunks: list[bytes] = []
+        self._stderr_chunks: list[bytes] = []
+        self.stdin = cast(TextIO, process.stdin)
+        self.stdout: InteractiveTextReader = _TranscriptReader(
+            cast(TextIO, process.stdout), self._budget, self._stdout_chunks
+        )
+        self.stderr: InteractiveTextReader = _TranscriptReader(
+            cast(TextIO, process.stderr), self._budget, self._stderr_chunks
+        )
+        self._monitor = threading.Thread(
+            target=self._enforce_timeout,
+            name=f"lean-runtime-process-{process.pid}",
+            daemon=True,
+        )
+        self._monitor.start()
+
+    def _enforce_timeout(self) -> None:
+        remaining = self._policy.timeout_seconds - (time.monotonic() - self._started)
+        if remaining > 0 and self._finished.wait(remaining):
+            return
+        if self._process.poll() is not None:
+            return
+        self._timed_out.set()
+        LocalBackend._stop(self._process)
+        try:
+            self._process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            LocalBackend._kill(self._process)
+
+    def poll(self) -> int | None:
+        return self._process.poll()
+
+    @staticmethod
+    def _remaining(reader: InteractiveTextReader) -> None:
+        with suppress(OSError, ValueError):
+            reader.read()
+
+    def finish(self) -> BackendResult:
+        if not self.stdin.closed:
+            self.stdin.close()
+        cancelled = False
+        try:
+            self._process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            cancelled = True
+            LocalBackend._stop(self._process)
+            try:
+                self._process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                LocalBackend._kill(self._process)
+                self._process.wait()
+        self._finished.set()
+        self._monitor.join(timeout=3)
+        self._remaining(self.stdout)
+        self._remaining(self.stderr)
+        self.stdout.close()
+        self.stderr.close()
+        timed_out = self._timed_out.is_set()
+        return BackendResult(
+            exit_code=124 if timed_out else 130 if cancelled else int(self._process.returncode),
+            stdout=b"".join(self._stdout_chunks).decode("utf-8", errors="replace"),
+            stderr=b"".join(self._stderr_chunks).decode("utf-8", errors="replace"),
+            elapsed_seconds=time.monotonic() - self._started,
+            timed_out=timed_out,
+            cancelled=cancelled and not timed_out,
+            output_truncated=self._budget.truncated,
+            enforced_policy_fields=self._enforced_policy_fields,
+        )
+
+
+class LocalBackend:
+    """Trusted local subprocess execution with bounded captured output."""
+
+    name = "local"
+
+    @staticmethod
+    def _process_options(
+        policy: ExecutionPolicy,
+    ) -> tuple[list[str], Callable[[], object] | None, int]:
+        if policy.network == "disabled":
+            raise PolicyError("the local backend cannot enforce network isolation")
+        enforced = ["timeout_seconds", "max_output_bytes"]
+        preexec = None
+        if os.name != "nt" and (policy.memory_mb or policy.cpu_seconds):
+            memory_mb = policy.memory_mb
+            cpu_seconds = policy.cpu_seconds
+
+            def apply_limits() -> None:
+                import resource
+
+                if memory_mb is not None:
+                    limit = memory_mb * 1024 * 1024
+                    getattr(resource, "setrlimit")(  # noqa: B009
+                        getattr(resource, "RLIMIT_AS"),  # noqa: B009
+                        (limit, limit),
+                    )
+                if cpu_seconds is not None:
+                    getattr(resource, "setrlimit")(  # noqa: B009
+                        getattr(resource, "RLIMIT_CPU"),  # noqa: B009
+                        (cpu_seconds, cpu_seconds),
+                    )
+
+            preexec = apply_limits
+            if memory_mb is not None:
+                enforced.append("memory_mb")
+            if cpu_seconds is not None:
+                enforced.append("cpu_seconds")
+        elif os.name == "nt" and (policy.memory_mb or policy.cpu_seconds):
+            raise PolicyError("the local Windows backend cannot enforce memory or CPU limits")
+        creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) if os.name == "nt" else 0
+        return enforced, preexec, creationflags
+
+    def spawn_interactive(
+        self,
+        command: Sequence[str],
+        *,
+        cwd: Path,
+        environment: Mapping[str, str],
+        policy: ExecutionPolicy,
+    ) -> InteractiveProcess:
+        """Spawn a trusted local process with live text pipes."""
+        enforced, preexec, creationflags = self._process_options(policy)
+        process = subprocess.Popen(
+            list(command),
+            cwd=cwd,
+            env=dict(environment),
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            bufsize=1,
+            start_new_session=os.name != "nt",
+            creationflags=creationflags,
+            preexec_fn=preexec,
+        )
+        return _LocalInteractiveProcess(
+            process,
+            policy=policy,
+            enforced_policy_fields=tuple(enforced),
+        )
+
+    def execute(
+        self,
+        command: Sequence[str],
+        *,
+        cwd: Path,
+        environment: Mapping[str, str],
+        policy: ExecutionPolicy,
+        cancel: threading.Event | None = None,
+    ) -> BackendResult:
+        enforced, preexec, creationflags = self._process_options(policy)
+
+        started = time.monotonic()
+        process = subprocess.Popen(
+            list(command),
+            cwd=cwd,
+            env=dict(environment),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=os.name != "nt",
+            creationflags=creationflags,
+            preexec_fn=preexec,
+        )
+        assert process.stdout is not None and process.stderr is not None
+        budget = _OutputBudget(policy.max_output_bytes)
+        stdout_chunks: list[bytes] = []
+        stderr_chunks: list[bytes] = []
+        readers = [
+            threading.Thread(target=_drain, args=(process.stdout, budget, stdout_chunks)),
+            threading.Thread(target=_drain, args=(process.stderr, budget, stderr_chunks)),
+        ]
+        for reader in readers:
+            reader.start()
+        timed_out = False
+        cancelled = False
+        while process.poll() is None:
+            if cancel is not None and cancel.is_set():
+                cancelled = True
+                self._stop(process)
+                break
+            if time.monotonic() - started >= policy.timeout_seconds:
+                timed_out = True
+                self._stop(process)
+                break
+            time.sleep(0.02)
+        try:
+            process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            self._kill(process)
+            process.wait()
+        for reader in readers:
+            reader.join()
+        exit_code = 130 if cancelled else 124 if timed_out else int(process.returncode)
+        return BackendResult(
+            exit_code=exit_code,
+            stdout=b"".join(stdout_chunks).decode("utf-8", errors="replace"),
+            stderr=b"".join(stderr_chunks).decode("utf-8", errors="replace"),
+            elapsed_seconds=time.monotonic() - started,
+            timed_out=timed_out,
+            cancelled=cancelled,
+            output_truncated=budget.truncated,
+            enforced_policy_fields=tuple(enforced),
+        )
+
+    @staticmethod
+    def _stop(process: subprocess.Popen[Any]) -> None:
+        try:
+            if os.name == "nt":
+                process.terminate()
+            else:
+                getattr(os, "killpg")(process.pid, signal.SIGTERM)  # noqa: B009
+        except ProcessLookupError:
+            pass
+
+    @staticmethod
+    def _kill(process: subprocess.Popen[Any]) -> None:
+        try:
+            if os.name == "nt":
+                process.kill()
+            else:
+                getattr(os, "killpg")(  # noqa: B009
+                    process.pid,
+                    getattr(signal, "SIGKILL"),  # noqa: B009
+                )
+        except ProcessLookupError:
+            pass

lean_runtime/cli.py

@@ -0,0 +1,254 @@
+"""Minimal command-line interface around the environment compiler."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .environments import ExecutionCapture
+from .errors import LeanRuntimeError, MaterializationError, ResolutionError
+from .events import RuntimeEvent
+from .lockfiles import EnvironmentLock
+from .models import ExecutionResult
+from .policies import ExecutionPolicy
+from .runtime import Runtime
+from .specs import EnvironmentSpec
+
+
+def _json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _progress(event: RuntimeEvent) -> None:
+    package = f" [{event.data['package']}]" if "package" in event.data else ""
+    print(f"lean-runtime: {event.kind}{package}: {event.message}", file=sys.stderr)
+
+
+def _cli_source_name(path: Path) -> str:
+    if path.is_absolute():
+        return path.name
+    return path.as_posix()
+
+
+def _emit_result(result: ExecutionResult, as_json: bool) -> None:
+    if as_json:
+        _json(result.to_dict())
+        return
+    if result.stdout:
+        print(result.stdout, end="" if result.stdout.endswith("\n") else "\n")
+    if result.stderr:
+        print(result.stderr, end="" if result.stderr.endswith("\n") else "\n", file=sys.stderr)
+    status = "accepted" if result.ok else "rejected"
+    environment = f" environment={result.environment_id}" if result.environment_id else ""
+    print(
+        f"{status}:{environment} toolchain={result.toolchain} "
+        f"exit={result.exit_code} elapsed={result.elapsed_seconds:.3f}s"
+    )
+
+
+def _policy(arguments: argparse.Namespace) -> ExecutionPolicy:
+    return ExecutionPolicy(
+        timeout_seconds=arguments.timeout,
+        max_output_bytes=arguments.max_output,
+        memory_mb=arguments.memory,
+        cpu_seconds=arguments.cpu,
+        network=arguments.network,
+    )
+
+
+def _add_policy(parser: argparse.ArgumentParser, *, timeout: float = 120) -> None:
+    parser.add_argument("--timeout", type=float, default=timeout)
+    parser.add_argument("--max-output", type=int, default=1_000_000)
+    parser.add_argument("--memory", type=int, help="memory limit in MiB")
+    parser.add_argument("--cpu", type=int, help="CPU time limit in seconds")
+    parser.add_argument("--network", choices=("inherit", "disabled"), default="inherit")
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="lean-runtime")
+    root.add_argument("--home", help="runtime store root")
+    root.add_argument("--quiet", action="store_true", help="suppress progress events")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    resolve = commands.add_parser("resolve", help="compile a TOML/JSON spec into a lock")
+    resolve.add_argument("spec", type=Path)
+    resolve.add_argument("--output", type=Path)
+    resolve.add_argument("--timeout", type=float, default=900)
+
+    ensure = commands.add_parser("ensure", help="build or reopen a locked environment")
+    ensure.add_argument("lock", type=Path)
+    ensure.add_argument("--name")
+
+    check = commands.add_parser(
+        "check", help="check with --with packages or in a published environment"
+    )
+    check.add_argument(
+        "inputs",
+        nargs="+",
+        help="FILE with --with, otherwise ENVIRONMENT FILE; FILE may be - for stdin",
+    )
+    check.add_argument(
+        "--with",
+        dest="package_refs",
+        action="append",
+        default=[],
+        metavar="REFERENCE",
+        help="repeatable github:owner/repository@tag-or-commit package reference",
+    )
+    check.add_argument("--toolchain", help="override the toolchain discovered from --with packages")
+    check.add_argument(
+        "--include", action="append", default=[], type=Path, help="additional Lean source file"
+    )
+    check.add_argument("--json", action="store_true")
+    _add_policy(check)
+
+    inspect = commands.add_parser("inspect", help="inspect a published environment")
+    inspect.add_argument("environment")
+    inspect.add_argument("--packages", action="store_true", help="include exact package locks")
+
+    commands.add_parser("env-list", help="list published environments")
+    commands.add_parser("cache-status", help="show cache counts and disk usage")
+    commands.add_parser("doctor", help="check local prerequisites and cache health")
+
+    replay = commands.add_parser("replay", help="replay a canonical execution capture")
+    replay.add_argument("capture", type=Path)
+    replay.add_argument("--json", action="store_true")
+
+    gc = commands.add_parser("gc", help="collect old unreferenced environments")
+    gc.add_argument("--execute", action="store_true", help="remove candidates; default is dry-run")
+    gc.add_argument("--minimum-age-hours", type=float, default=24 * 30)
+
+    raw = commands.add_parser("raw-check", help="check without a managed environment")
+    raw.add_argument("file", type=Path, help="Lean source file, or - for stdin")
+    raw.add_argument("--toolchain")
+    raw.add_argument("--project", type=Path)
+    raw.add_argument("--json", action="store_true")
+    _add_policy(raw)
+
+    build = commands.add_parser("project-build", help="build an existing Lake project")
+    build.add_argument("project", type=Path)
+    build.add_argument("targets", nargs="*")
+    build.add_argument("--toolchain")
+    build.add_argument("--timeout", type=float, default=900)
+    build.add_argument("--json", action="store_true")
+
+    install = commands.add_parser("install", help="install a Lean toolchain")
+    install.add_argument("toolchain")
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    runtime = Runtime(home=args.home, on_event=None if args.quiet else _progress)
+    try:
+        if args.command == "install":
+            print(runtime.toolchains.ensure(args.toolchain))
+            return 0
+        if args.command == "resolve":
+            lock = runtime.resolve(EnvironmentSpec.load(args.spec), timeout=args.timeout)
+            if args.output:
+                lock.write(args.output)
+                print(lock.lock_id)
+            else:
+                _json(lock.to_dict())
+            return 0
+        if args.command == "ensure":
+            environment = runtime.ensure(EnvironmentLock.load(args.lock), name=args.name)
+            _json(environment.inspect().to_dict())
+            return 0
+        if args.command == "inspect":
+            environment = runtime.open(args.environment)
+            payload = environment.inspect().to_dict()
+            if args.packages:
+                payload["package_locks"] = [
+                    package.to_dict() for package in environment.lock.packages
+                ]
+            _json(payload)
+            return 0
+        if args.command == "env-list":
+            _json(list(runtime.list_environments()))
+            return 0
+        if args.command == "cache-status":
+            _json(runtime.store_status().to_dict())
+            return 0
+        if args.command == "doctor":
+            doctor_report = runtime.doctor()
+            _json(doctor_report.to_dict())
+            return 0 if doctor_report.ok else 2
+        if args.command == "replay":
+            capture = ExecutionCapture.load(args.capture)
+            result = runtime.replay_capture(capture)
+            _emit_result(result, args.json)
+            if capture.expected_ok is not None and result.ok != capture.expected_ok:
+                return 1
+            return 0 if result.ok else 1
+        if args.command == "gc":
+            gc_report = runtime.gc(
+                dry_run=not args.execute,
+                minimum_age_seconds=args.minimum_age_hours * 3600,
+            )
+            _json(gc_report.to_dict())
+            return 0
+        if args.command == "check":
+            if args.package_refs:
+                if len(args.inputs) != 1:
+                    raise ValueError("check with --with expects exactly one FILE")
+                environment = runtime.ensure_references(args.package_refs, toolchain=args.toolchain)
+                source_file = Path(args.inputs[0])
+            else:
+                if len(args.inputs) != 2:
+                    raise ValueError("check expects ENVIRONMENT FILE, or FILE with --with")
+                if args.toolchain:
+                    raise ValueError("check --toolchain is only valid with --with")
+                environment = runtime.open(args.inputs[0])
+                source_file = Path(args.inputs[1])
+            if str(source_file) == "-":
+                if args.include:
+                    raise ValueError("stdin entrypoints cannot be combined with --include")
+                result = environment.check(sys.stdin.read(), policy=_policy(args))
+            else:
+                source_paths = [source_file, *args.include]
+                files = {_cli_source_name(path): path.read_text() for path in source_paths}
+                result = environment.check_files(
+                    files,
+                    entrypoint=_cli_source_name(source_file),
+                    policy=_policy(args),
+                )
+        elif args.command == "raw-check":
+            source = sys.stdin.read() if str(args.file) == "-" else args.file.read_text()
+            result = runtime.check(
+                source,
+                toolchain=args.toolchain,
+                project=args.project,
+                policy=_policy(args),
+            )
+        else:
+            result = runtime.build(
+                args.project,
+                targets=args.targets,
+                toolchain=args.toolchain,
+                timeout=args.timeout,
+            )
+    except (ResolutionError, MaterializationError) as exc:
+        _json(
+            {
+                "error": str(exc),
+                "phase": exc.phase,
+                "command": list(exc.command),
+                "exit_code": exc.exit_code,
+                "output": exc.output,
+            }
+        )
+        return 2
+    except (LeanRuntimeError, OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        print(f"lean-runtime: {exc}", file=sys.stderr)
+        return 2
+    _emit_result(result, args.json)
+    return 0 if result.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())