lean-runtime 0.6.0__py3-none-any.whl

lean_runtime/errors.py

@@ -0,0 +1,63 @@
+"""Exceptions raised by :mod:`lean_runtime`."""
+
+
+class LeanRuntimeError(RuntimeError):
+    """Base class for runtime infrastructure failures."""
+
+
+class ToolchainError(LeanRuntimeError):
+    """A Lean toolchain could not be resolved or installed."""
+
+
+class ProjectError(LeanRuntimeError):
+    """A Lean project is missing required configuration."""
+
+
+class SpecificationError(LeanRuntimeError):
+    """An environment specification is invalid."""
+
+
+class ResolutionError(LeanRuntimeError):
+    """Lake could not resolve an environment specification."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        phase: str = "resolution",
+        command: tuple[str, ...] = (),
+        exit_code: int | None = None,
+        output: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.phase = phase
+        self.command = command
+        self.exit_code = exit_code
+        self.output = output
+
+
+class EnvironmentError(LeanRuntimeError):
+    """A content-addressed environment could not be opened or built."""
+
+
+class MaterializationError(EnvironmentError):
+    """Locked sources or build artifacts could not be materialized."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        phase: str,
+        command: tuple[str, ...] = (),
+        exit_code: int | None = None,
+        output: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.phase = phase
+        self.command = command
+        self.exit_code = exit_code
+        self.output = output
+
+
+class PolicyError(LeanRuntimeError):
+    """An execution policy cannot be enforced by the selected backend."""

lean_runtime/events.py

@@ -0,0 +1,35 @@
+"""Structured progress events emitted by long-running runtime operations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeEvent:
+    """One observable lifecycle transition."""
+
+    kind: str
+    message: str
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+EventCallback = Callable[[RuntimeEvent], None]
+
+
+class EventEmitter:
+    """Null-safe adapter shared by runtime components."""
+
+    def __init__(self, callback: EventCallback | None = None) -> None:
+        self.callback = callback
+
+    def emit(self, kind: str, message: str, **data: Any) -> None:
+        if self.callback is not None:
+            self.callback(RuntimeEvent(kind=kind, message=message, data=data))

lean_runtime/health.py

@@ -0,0 +1,86 @@
+"""Local installation and cache health checks."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+from .errors import ToolchainError
+from .store import EnvironmentStore
+from .toolchains import ToolchainManager
+
+CheckStatus = Literal["pass", "warning", "fail"]
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorCheck:
+    name: str
+    status: CheckStatus
+    message: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorReport:
+    checks: tuple[DoctorCheck, ...]
+
+    @property
+    def ok(self) -> bool:
+        return all(check.status != "fail" for check in self.checks)
+
+    def to_dict(self) -> dict[str, object]:
+        return {"ok": self.ok, "checks": [check.to_dict() for check in self.checks]}
+
+
+def diagnose(toolchains: ToolchainManager, store: EnvironmentStore) -> DoctorReport:
+    """Inspect prerequisites without downloading or building anything."""
+    checks: list[DoctorCheck] = []
+    git = shutil.which("git")
+    if git is None:
+        checks.append(DoctorCheck("git", "fail", "Git is not available on PATH"))
+    else:
+        process = subprocess.run([git, "--version"], text=True, capture_output=True, check=False)
+        status: CheckStatus = "pass" if process.returncode == 0 else "fail"
+        checks.append(DoctorCheck("git", status, process.stdout.strip() or "Git failed"))
+
+    try:
+        with tempfile.NamedTemporaryFile(dir=store.home, prefix="doctor-", delete=True):
+            pass
+        checks.append(DoctorCheck("store", "pass", f"Store is writable: {store.home}"))
+    except OSError as exc:
+        checks.append(DoctorCheck("store", "fail", f"Store is not writable: {exc}"))
+
+    free = shutil.disk_usage(store.home).free
+    if free < 256 * 1024 * 1024:
+        checks.append(DoctorCheck("disk", "fail", f"Only {free // (1024**2)} MiB free"))
+    elif free < 2 * 1024 * 1024 * 1024:
+        checks.append(DoctorCheck("disk", "warning", f"Only {free // (1024**2)} MiB free"))
+    else:
+        checks.append(DoctorCheck("disk", "pass", f"{free // (1024**3)} GiB free"))
+
+    try:
+        elan = toolchains.elan_path(bootstrap=False)
+    except ToolchainError:
+        if os.name != "nt" and platform.system() in {"Darwin", "Linux"}:
+            checks.append(
+                DoctorCheck("elan", "warning", "Private Elan is not installed; it will bootstrap")
+            )
+        else:
+            checks.append(
+                DoctorCheck("elan", "fail", "Set LEAN_RUNTIME_ELAN to an Elan executable")
+            )
+    else:
+        checks.append(DoctorCheck("elan", "pass", f"Elan executable: {elan}"))
+
+    staging = tuple(store.environments.glob(".staging-*"))
+    status = "warning" if staging else "pass"
+    message = f"{len(staging)} incomplete staging directories" if staging else "No stale builds"
+    checks.append(DoctorCheck("staging", status, message))
+    return DoctorReport(tuple(checks))

lean_runtime/lake.py

@@ -0,0 +1,43 @@
+"""Synthetic Lake root generation."""
+
+from __future__ import annotations
+
+import json
+
+from .specs import EnvironmentSpec
+
+ROOT_PACKAGE = "lean_runtime_environment"
+ROOT_MODULE = "LeanRuntimeEnvironment"
+
+
+def _quote(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def generate_lakefile(spec: EnvironmentSpec) -> str:
+    lines = [
+        f"name = {_quote(ROOT_PACKAGE)}",
+        'version = "0.0.0"',
+        'defaultTargets = ["LeanRuntimeEnvironment"]',
+        "",
+    ]
+    for package in sorted(spec.packages, key=lambda item: item.name):
+        revision = package.rev.lower() if package.revision_kind == "commit" else package.rev
+        lines.extend(
+            [
+                "[[require]]",
+                f"name = {_quote(package.name)}",
+                f"git = {_quote(package.url)}",
+                f"rev = {_quote(revision)}",
+            ]
+        )
+        if package.subdir:
+            lines.append(f"subDir = {_quote(package.subdir)}")
+        lines.append("")
+    lines.extend(["[[lean_lib]]", f"name = {_quote(ROOT_MODULE)}", ""])
+    return "\n".join(lines)
+
+
+def generate_root_module(spec: EnvironmentSpec) -> str:
+    imports = [f"import {package.module}" for package in spec.packages]
+    return "\n".join([*imports, "", "/- Generated by Lean Runtime. -/", ""])

lean_runtime/lockfiles.py

@@ -0,0 +1,192 @@
+"""Portable environment locks produced by Lake-backed resolution."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import EnvironmentError
+from .serialization import sha256_id, write_json_atomic
+
+LOCK_SCHEMA = "lean-runtime-environment-lock/1"
+_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_'-]*")
+_MODULE = re.compile(r"[A-Za-z_][A-Za-z0-9_']*(?:\.[A-Za-z_][A-Za-z0-9_']*)*")
+_COMMIT = re.compile(r"[0-9a-fA-F]{40}")
+_SOURCE_ID = re.compile(r"source_[0-9a-f]{64}")
+_SPEC_ID = re.compile(r"spec_[0-9a-f]{64}")
+
+
+def _optional_string(value: Any, field_name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise EnvironmentError(f"lock field {field_name!r} must be a string or null")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class LockedPackage:
+    name: str
+    url: str
+    revision: str
+    source_id: str
+    tree_hash: str
+    requested_revision: str | None = None
+    inherited: bool = False
+    subdir: str | None = None
+    root_module: str | None = None
+    artifact_command: tuple[str, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if _NAME.fullmatch(self.name) is None:
+            raise EnvironmentError(f"invalid locked package name: {self.name!r}")
+        if not self.url or "\n" in self.url or "\r" in self.url:
+            raise EnvironmentError(f"invalid locked Git URL for package {self.name!r}")
+        if _COMMIT.fullmatch(self.revision) is None:
+            raise EnvironmentError(f"invalid locked revision for package {self.name!r}")
+        if _COMMIT.fullmatch(self.tree_hash) is None:
+            raise EnvironmentError(f"invalid locked tree hash for package {self.name!r}")
+        if _SOURCE_ID.fullmatch(self.source_id) is None:
+            raise EnvironmentError(f"invalid source identity for package {self.name!r}")
+        if self.requested_revision is not None and not self.requested_revision:
+            raise EnvironmentError(f"empty requested revision for package {self.name!r}")
+        if self.root_module is not None and _MODULE.fullmatch(self.root_module) is None:
+            raise EnvironmentError(f"invalid root module for package {self.name!r}")
+        if self.subdir is not None:
+            subdir = Path(self.subdir)
+            if not self.subdir or subdir.is_absolute() or ".." in subdir.parts:
+                raise EnvironmentError(f"unsafe package subdir in lock: {self.subdir!r}")
+        if any(not item or "\x00" in item for item in self.artifact_command):
+            raise EnvironmentError(f"invalid artifact command for package {self.name!r}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "source": "git",
+            "url": self.url,
+            "requested_revision": self.requested_revision,
+            "revision": self.revision,
+            "tree_hash": self.tree_hash,
+            "source_id": self.source_id,
+            "inherited": self.inherited,
+            "subdir": self.subdir,
+            "root_module": self.root_module,
+            "artifact_command": list(self.artifact_command),
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> LockedPackage:
+        if value.get("source") != "git":
+            raise EnvironmentError("lock contains an unsupported package source")
+        command = value.get("artifact_command", [])
+        if not isinstance(command, list) or not all(isinstance(item, str) for item in command):
+            raise EnvironmentError("locked artifact_command must be an array of strings")
+        inherited = value.get("inherited", False)
+        if not isinstance(inherited, bool):
+            raise EnvironmentError("locked package inherited must be Boolean")
+        required = ("name", "url", "revision", "tree_hash", "source_id")
+        if any(not isinstance(value.get(key), str) for key in required):
+            raise EnvironmentError("locked package is missing a required string field")
+        return cls(
+            name=value["name"],
+            url=value["url"],
+            requested_revision=_optional_string(
+                value.get("requested_revision"), "requested_revision"
+            ),
+            revision=value["revision"],
+            tree_hash=value["tree_hash"],
+            source_id=value["source_id"],
+            inherited=inherited,
+            subdir=_optional_string(value.get("subdir"), "subdir"),
+            root_module=_optional_string(value.get("root_module"), "root_module"),
+            artifact_command=tuple(command),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentLock:
+    """A canonical, platform-independent resolved dependency graph."""
+
+    toolchain: str
+    spec_digest: str
+    root_lakefile: str
+    root_module: str
+    manifest: dict[str, Any]
+    packages: tuple[LockedPackage, ...]
+
+    def __post_init__(self) -> None:
+        if not self.toolchain or "\x00" in self.toolchain:
+            raise EnvironmentError("lock contains an invalid toolchain")
+        if _SPEC_ID.fullmatch(self.spec_digest) is None:
+            raise EnvironmentError("lock contains an invalid specification digest")
+        if not self.root_lakefile or "\x00" in self.root_lakefile:
+            raise EnvironmentError("lock contains an invalid root Lake configuration")
+        if "\x00" in self.root_module:
+            raise EnvironmentError("lock contains invalid root Lean source")
+        names = [package.name for package in self.packages]
+        if len(names) != len(set(names)):
+            raise EnvironmentError("lock contains duplicate package names")
+
+    def identity_payload(self) -> dict[str, Any]:
+        return {
+            "schema": LOCK_SCHEMA,
+            "toolchain": self.toolchain,
+            "spec_digest": self.spec_digest,
+            "root_lakefile": self.root_lakefile,
+            "root_module": self.root_module,
+            "manifest": self.manifest,
+            "packages": [
+                package.to_dict() for package in sorted(self.packages, key=lambda item: item.name)
+            ],
+        }
+
+    @property
+    def lock_id(self) -> str:
+        return sha256_id("lock", self.identity_payload())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"lock_id": self.lock_id, **self.identity_payload()}
+
+    def write(self, path: str | Path) -> None:
+        write_json_atomic(Path(path), self.to_dict())
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> EnvironmentLock:
+        if value.get("schema") != LOCK_SCHEMA:
+            raise EnvironmentError(f"unsupported lock schema: {value.get('schema')!r}")
+        required_strings = ("toolchain", "spec_digest", "root_lakefile", "root_module")
+        if any(not isinstance(value.get(key), str) for key in required_strings):
+            raise EnvironmentError("environment lock is missing a required string field")
+        manifest = value.get("manifest")
+        packages = value.get("packages")
+        if not isinstance(manifest, dict):
+            raise EnvironmentError("environment lock manifest must be an object")
+        if not isinstance(packages, list) or not all(isinstance(item, dict) for item in packages):
+            raise EnvironmentError("environment lock packages must be an array of objects")
+        lock = cls(
+            toolchain=value["toolchain"],
+            spec_digest=value["spec_digest"],
+            root_lakefile=value["root_lakefile"],
+            root_module=value["root_module"],
+            manifest=manifest,
+            packages=tuple(LockedPackage.from_dict(item) for item in packages),
+        )
+        recorded = value.get("lock_id")
+        if recorded is not None and recorded != lock.lock_id:
+            raise EnvironmentError(
+                f"lock identity mismatch: recorded {recorded!r}, computed {lock.lock_id!r}"
+            )
+        return lock
+
+    @classmethod
+    def load(cls, path: str | Path) -> EnvironmentLock:
+        try:
+            value = json.loads(Path(path).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise EnvironmentError(f"could not read environment lock: {path}") from exc
+        if not isinstance(value, dict):
+            raise EnvironmentError("environment lock must contain an object")
+        return cls.from_dict(value)

lean_runtime/locking.py

@@ -0,0 +1,82 @@
+"""Small cross-process file locks used for atomic store publication."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from types import TracebackType
+from typing import BinaryIO
+
+from .errors import EnvironmentError
+
+
+class FileLock:
+    def __init__(self, path: Path, timeout: float = 300) -> None:
+        self.path = path
+        self.timeout = timeout
+        self._handle: BinaryIO | None = None
+
+    def __enter__(self) -> FileLock:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        handle = self.path.open("a+b")
+        started = time.monotonic()
+        while True:
+            try:
+                if os.name == "nt":
+                    import msvcrt
+
+                    handle.seek(0)
+                    if handle.tell() == 0:
+                        handle.write(b"0")
+                        handle.flush()
+                    handle.seek(0)
+                    getattr(msvcrt, "locking")(  # noqa: B009
+                        handle.fileno(),
+                        getattr(msvcrt, "LK_NBLCK"),  # noqa: B009
+                        1,  # noqa: B009
+                    )
+                else:
+                    import fcntl
+
+                    getattr(fcntl, "flock")(  # noqa: B009
+                        handle.fileno(),
+                        getattr(fcntl, "LOCK_EX") | getattr(fcntl, "LOCK_NB"),  # noqa: B009
+                    )
+                self._handle = handle
+                return self
+            except OSError as error:
+                if time.monotonic() - started >= self.timeout:
+                    handle.close()
+                    raise EnvironmentError(
+                        f"timed out waiting for store lock: {self.path}"
+                    ) from error
+                time.sleep(0.05)
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        handle = self._handle
+        if handle is None:
+            return
+        if os.name == "nt":
+            import msvcrt
+
+            handle.seek(0)
+            getattr(msvcrt, "locking")(  # noqa: B009
+                handle.fileno(),
+                getattr(msvcrt, "LK_UNLCK"),  # noqa: B009
+                1,  # noqa: B009
+            )
+        else:
+            import fcntl
+
+            getattr(fcntl, "flock")(  # noqa: B009
+                handle.fileno(),
+                getattr(fcntl, "LOCK_UN"),  # noqa: B009
+            )
+        handle.close()
+        self._handle = None

lean_runtime/models.py

@@ -0,0 +1,78 @@
+"""Stable result models returned by the runtime."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+Severity = Literal["error", "warning", "information", "unknown"]
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """One compiler diagnostic parsed from Lean's textual output."""
+
+    severity: Severity
+    message: str
+    file: str | None = None
+    line: int | None = None
+    column: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PackageProvenance:
+    name: str
+    url: str
+    revision: str
+    tree_hash: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionProvenance:
+    environment_id: str | None
+    execution_id: str
+    request_digest: str
+    lock_id: str | None
+    toolchain: str
+    packages: tuple[PackageProvenance, ...]
+    platform: dict[str, str]
+    backend: str
+    requested_policy: dict[str, Any]
+    enforced_policy_fields: tuple[str, ...]
+    source_digest: str
+    started_at: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionResult:
+    """The reproducible outcome of one Lean or Lake invocation."""
+
+    ok: bool
+    exit_code: int
+    toolchain: str
+    command: tuple[str, ...]
+    cwd: str
+    stdout: str
+    stderr: str
+    elapsed_seconds: float
+    timed_out: bool = False
+    cancelled: bool = False
+    output_truncated: bool = False
+    diagnostics: tuple[Diagnostic, ...] = field(default_factory=tuple)
+    provenance: ExecutionProvenance | None = None
+
+    @property
+    def environment_id(self) -> str | None:
+        return self.provenance.environment_id if self.provenance else None
+
+    @property
+    def execution_id(self) -> str | None:
+        return self.provenance.execution_id if self.provenance else None
+
+    @property
+    def lock_id(self) -> str | None:
+        return self.provenance.lock_id if self.provenance else None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable representation."""
+        return asdict(self)

lean_runtime/policies.py

@@ -0,0 +1,36 @@
+"""Backend-independent execution policy requests."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+NetworkPolicy = Literal["inherit", "disabled"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionPolicy:
+    timeout_seconds: float = 120
+    max_output_bytes: int = 1_000_000
+    memory_mb: int | None = None
+    cpu_seconds: int | None = None
+    network: NetworkPolicy = "inherit"
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        if self.max_output_bytes < 0:
+            raise ValueError("max_output_bytes must be nonnegative")
+        if self.memory_mb is not None and self.memory_mb <= 0:
+            raise ValueError("memory_mb must be positive")
+        if self.cpu_seconds is not None and self.cpu_seconds <= 0:
+            raise ValueError("cpu_seconds must be positive")
+        if self.network not in {"inherit", "disabled"}:
+            raise ValueError(f"unsupported network policy: {self.network!r}")
+
+    @classmethod
+    def trusted_local(cls, **kwargs: Any) -> ExecutionPolicy:
+        return cls(**kwargs)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

lean_runtime/py.typed

@@ -0,0 +1 @@
+