lean-runtime 4.0.0__tar.gz → 4.0.1__tar.gz

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 4.0.1 - 2026-08-18
+
+- Keep `verify ENV --offline` strictly local for sparse environments by probing
+  a retained capsule module and forbidding projection acquisition during the
+  probe.
+- Pin the selected exact toolchain before project scaffolding and put a reused
+  user toolchain ahead of private Elan for nested Lake commands, preventing
+  `new --core` from downloading an alternate unprefixed toolchain.
+
 ## 4.0.0 - 2026-08-18
 
 - Replace the implementation-shaped CLI with a cwd-first workflow: `new`,

{lean_runtime-4.0.0/lean_runtime.egg-info → lean_runtime-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 4.0.0
+Version: 4.0.1
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -194,6 +194,5 @@ interfaces for infrastructure code.
 - Logical Lean rejections exit 1; invalid/infrastructure invocations exit 2;
   publication failures retain their documented classified exit statuses.
 
-Documentation lives in [`docs/`](docs/index.md). Start with
-[`docs/getting-started.md`](docs/getting-started.md),
-[`docs/cli.md`](docs/cli.md), and [`docs/local-projects.md`](docs/local-projects.md).
+Documentation lives at
+[alerad.github.io/lean-runtime](https://alerad.github.io/lean-runtime/).

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/README.md

@@ -158,6 +158,5 @@ interfaces for infrastructure code.
 - Logical Lean rejections exit 1; invalid/infrastructure invocations exit 2;
   publication failures retain their documented classified exit statuses.
 
-Documentation lives in [`docs/`](docs/index.md). Start with
-[`docs/getting-started.md`](docs/getting-started.md),
-[`docs/cli.md`](docs/cli.md), and [`docs/local-projects.md`](docs/local-projects.md).
+Documentation lives at
+[alerad.github.io/lean-runtime](https://alerad.github.io/lean-runtime/).

lean_runtime-4.0.1/docs/getting-started.md

@@ -0,0 +1,132 @@
+# Installation and first check
+
+This guide takes you from an empty Python environment to a checked Lean proof.
+Choose the path that matches what you already have; Lean Runtime infers the
+rest from the current directory and the source itself.
+
+## Requirements
+
+- Python 3.10 or newer;
+- Git on `PATH`;
+- Linux or macOS.
+
+An existing Elan installation is useful but not required. When the exact
+toolchain is already present, Lean Runtime uses its binaries read-only. Missing
+toolchains are kept in Lean Runtime's private store.
+
+## Install
+
+Installing in a virtual environment keeps the command isolated from unrelated
+Python tools:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install lean-runtime
+lean-runtime --version
+```
+
+The installed wheel provides one executable: `lean-runtime`.
+
+## Choose your first workflow
+
+=== "Standalone file"
+
+    Create `Main.lean`:
+
+    ```lean
+    import Mathlib.Data.Nat.Prime.Basic
+
+    example : Nat.Prime 5 := by decide
+    ```
+
+    Check it:
+
+    ```bash
+    lean-runtime check Main.lean
+    ```
+
+    Outside a Lake project, Lean Runtime analyzes the imports, selects an exact
+    catalog environment, and acquires the required verified import closure. The
+    second check reuses that environment.
+
+=== "New project"
+
+    ```bash
+    lean-runtime new MyProof
+    cd MyProof
+    lean-runtime check
+    lean-runtime build
+    ```
+
+    `new` selects a stable cataloged Mathlib/toolchain pair, writes exact Lake
+    metadata, and prepares reusable dependencies. Mutating commands show their
+    plan before acting; use `--yes` only for non-interactive automation.
+
+=== "Existing Lake project"
+
+    ```bash
+    cd ExistingProject
+    lean-runtime check
+    lean-runtime adopt
+    ```
+
+    Checking works before adoption. `adopt` is an optional storage optimization:
+    it verifies the pinned manifest and current dependency checkouts, previews
+    reuse and recovery, probes a shared graph, and swaps it atomically. It does
+    not update `lean-toolchain` or `lake-manifest.json`.
+
+=== "Python"
+
+    ```python
+    import lean_runtime as lean
+
+    env = lean.setup(deps=["mathlib@v4.33.0"])
+    result = env.check("import Mathlib.Data.Nat.Prime.Basic\nexample : Nat.Prime 5 := by decide\n")
+    result.raise_for_error()
+    print(result.execution_id)
+    ```
+
+    Keep the returned environment and call it repeatedly; setup and acquired
+    artifacts are reused.
+
+## Understand what happened
+
+```bash
+lean-runtime status Main.lean
+lean-runtime storage usage
+lean-runtime doctor
+```
+
+`status` explains context selection, `storage usage` reports retained content,
+and `doctor` checks Git, disk, store health, toolchains, staging areas, and
+abandoned workspaces.
+
+For a standalone check, save the exact selected context when you want a durable
+artifact:
+
+```bash
+lean-runtime check Main.lean --lock-out environment.lock.json
+lean-runtime check Main.lean --using environment.lock.json --offline
+```
+
+`--offline` is fail-closed: missing toolchains, environments, or sparse import
+closures produce an error instead of a network request.
+
+## Where to go next
+
+- [Standalone files](standalone-files.md) — frontmatter, explicit context, watch,
+  and matrix checks.
+- [Lake projects](local-projects.md) — focused checking, adoption, shared
+  dependencies, and updates.
+- [Python API](python-api.md) — batch, async, cancellation, multi-file, and
+  interactive use.
+- [Trust and limitations](trust-and-limitations.md) — the exact integrity and
+  execution boundary.
+
+??? question "Something failed on the first run?"
+
+    Run `lean-runtime doctor`, then repeat with `--verbose`. A completed Lean
+    rejection exits 1; an invalid invocation or infrastructure failure exits 2.
+    The [CLI reference](cli.md#exit-status) lists all public exit classes.

lean_runtime-4.0.1/docs/index.md

@@ -0,0 +1,150 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+<div class="lr-hero" markdown>
+
+<span class="lr-eyebrow">LEAN 4 ENVIRONMENTS, WITHOUT THE BUSYWORK</span>
+
+# Check the proof. Reuse everything else.
+
+Lean Runtime gives standalone files, Lake projects, and Python programs one
+exact, cache-aware way to run Lean. It discovers the right context, reuses
+compatible toolchains and dependencies, and records precisely what ran.
+
+[Get started](getting-started.md){ .md-button .md-button--primary }
+[Explore the CLI](cli.md){ .md-button }
+
+```bash
+python -m pip install lean-runtime
+lean-runtime check Main.lean
+```
+
+</div>
+
+<div class="lr-proof-line" markdown>
+
+**One command** · **Exact dependency graphs** · **Warm and offline reuse** ·
+**Structured provenance**
+
+</div>
+
+## Start from where you are
+
+<div class="grid cards" markdown>
+
+-   :material-file-code-outline:{ .lg .middle } **I have a Lean file**
+
+    ---
+
+    Let imports describe the environment. Lean Runtime discovers an exact
+    compatible Mathlib release, acquires only the required capsule closure,
+    and keeps diagnostics on your original filename.
+
+    [`lean-runtime check Main.lean` →](standalone-files.md)
+
+-   :material-folder-cog-outline:{ .lg .middle } **I have a Lake project**
+
+    ---
+
+    Work in the current directory. Keep the existing toolchain and manifest;
+    optionally adopt shared dependency storage without changing revisions.
+
+    [`lean-runtime check` →](local-projects.md)
+
+-   :material-creation-outline:{ .lg .middle } **I want a new project**
+
+    ---
+
+    Create a catalog-pinned project with exact Lake metadata and a reusable
+    dependency graph, then check it immediately.
+
+    [`lean-runtime new MyProof` →](getting-started.md#new-project)
+
+-   :material-language-python:{ .lg .middle } **I am calling Lean from Python**
+
+    ---
+
+    Prepare once, check many sources, run batches concurrently, and retain
+    typed diagnostics, cancellation, identities, and provenance.
+
+    [`lean.setup(...)` →](python-api.md)
+
+</div>
+
+## A small daily interface
+
+```text
+new NAME       create a project
+adopt [PATH]   share exact dependencies from existing projects
+check [PATH…]  check a project, directory, source file, or stdin
+watch FILE     re-check on save
+build [TARGET] build the current project
+update         preview and apply a transactional dependency update
+status [PATH]  explain what Lean Runtime selected
+```
+
+Project commands default to the current directory. `check` uses the nearest
+pinned Lake project when one exists and performs bounded exact-environment
+discovery otherwise. Advanced storage and publication machinery stays under
+noun namespaces such as `env`, `project`, `program`, and `toolchain`.
+
+[Command-line reference](cli.md){ .md-button }
+
+## Exact when it matters
+
+<div class="lr-pipeline" markdown>
+
+```text
+source or project
+       │
+       ▼
+context discovery ──► exact lock ──► verified environment
+                                            │
+                                            ▼
+                                      Lean execution
+                                            │
+                                            ▼
+                         result + diagnostics + provenance
+```
+
+</div>
+
+Lean Runtime treats identity and lifecycle as product features:
+
+- package tags resolve to full Git commits and tree hashes;
+- locks and environments have canonical content-derived identities;
+- sparse capsules verify manifests, frame digests, and projected artifacts;
+- identical requests share a request digest while each attempt gets a unique
+  execution ID;
+- acquisition, project sharing, and updates stage and probe before publication;
+- compatible user Elan toolchains are reused read-only.
+
+[How environments work](environments.md){ .md-button }
+[Architecture](architecture.md){ .md-button }
+
+!!! warning "Trusted execution, not a sandbox"
+
+    Lean packages and Lake configuration can execute native programs and build
+    commands. Lean Runtime verifies identities and artifacts, but its local
+    backend is intended for trusted inputs. Read the
+    [trust boundary](trust-and-limitations.md) before running third-party locks
+    or packages.
+
+## Go deeper
+
+<div class="grid cards" markdown>
+
+- **Portable environments** — export complete copies or acquire source-free
+  sparse capsules from OCI libraries. [Read the guide →](portable-copies.md)
+- **Verification and replay** — inspect exact identities, capture executions,
+  compare environments, and replay requests. [Verification →](v1-precision.md)
+- **Publishing** — generate a multi-platform GitHub workflow with isolated
+  capsule probes, signatures, and clean-consumer checks.
+  [Publishing guide →](project-publishing.md)
+- **Python automation** — use synchronous, async, batch, multi-file, matrix,
+  interactive, and cancellation APIs. [Python reference →](python-api.md)
+
+</div>

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/lean_runtime/environments.py

@@ -530,6 +530,7 @@ class Environment:
         filename: str = "Main.lean",
         policy: ExecutionPolicy | None = None,
         cancel: threading.Event | None = None,
+        _allow_sparse_acquisition: bool = True,
     ) -> ExecutionResult:
         safe_filename = Path(filename).name
         if not safe_filename.endswith(".lean"):
@@ -539,6 +540,7 @@ class Environment:
             entrypoint=safe_filename,
             policy=policy,
             cancel=cancel,
+            _allow_sparse_acquisition=_allow_sparse_acquisition,
         )
 
     def check_files(
@@ -548,6 +550,7 @@ class Environment:
         entrypoint: str = "Main.lean",
         policy: ExecutionPolicy | None = None,
         cancel: threading.Event | None = None,
+        _allow_sparse_acquisition: bool = True,
     ) -> ExecutionResult:
         """Check a safe relative tree of Lean files through one entrypoint."""
         normalized = _source_files(files)
@@ -559,7 +562,12 @@ class Environment:
                 module for source in normalized.values() for module in source_import_roots(source)
             )
         )
-        self.manager.ensure_sparse_modules(self.lock, roots, frozenset({"check"}))
+        self.manager.ensure_sparse_modules(
+            self.lock,
+            roots,
+            frozenset({"check"}),
+            allow_acquisition=_allow_sparse_acquisition,
+        )
         return self._execute_in_instance(
             operation="check",
             files=normalized,
@@ -1112,6 +1120,8 @@ class EnvironmentManager:
         lock: EnvironmentLock,
         roots: tuple[str, ...],
         capabilities: frozenset[str],
+        *,
+        allow_acquisition: bool = True,
     ) -> None:
         """Extend a sparse projection before checking a new import closure."""
         environment_id = environment_identity(lock)
@@ -1130,6 +1140,11 @@ class EnvironmentManager:
                 for artifact in required
             ):
                 return
+            if not allow_acquisition:
+                raise EnvironmentError(
+                    "the retained sparse projection is missing artifacts required by this "
+                    "operation; offline verification does not permit acquisition"
+                )
             if self.sparse_acquirer is None:
                 raise EnvironmentError("sparse environment has no configured acquisition source")
             self.sparse_acquirer(lock, roots, capabilities)

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/lean_runtime/runtime.py

@@ -1909,6 +1909,11 @@ class Runtime:
         published_entries: list[Path] = []
         modified_existing: dict[Path, bytes] = {}
         try:
+            # Lake chooses its own release channel during `lake init` when the
+            # destination has no pin. Publish the already-selected exact pin
+            # before invoking it so nested Lake/Elan calls cannot select or
+            # install a spelling different from the one the plan verified.
+            (staging / "lean-toolchain").write_text(plan.toolchain + "\n", encoding="utf-8")
             custom_agents = target / "AGENTS.md"
             if custom_agents.is_file():
                 (staging / "AGENTS.md").write_bytes(custom_agents.read_bytes())
@@ -1921,10 +1926,16 @@ class Runtime:
                 plan.project_name or target.name,
                 "lib",
             )
+            environment_for = getattr(self.toolchains, "environment_for", None)
+            command_environment = (
+                environment_for(plan.toolchain)
+                if callable(environment_for)
+                else self.toolchains.environment
+            )
             process = subprocess.run(
                 command,
                 cwd=staging,
-                env=self.toolchains.environment,
+                env=command_environment,
                 text=True,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.STDOUT,
@@ -1935,6 +1946,7 @@ class Runtime:
                 raise ProjectError(
                     "Lake could not initialize the project" + (f":\n{detail}" if detail else "")
                 )
+            (staging / "lean-toolchain").write_text(plan.toolchain + "\n", encoding="utf-8")
             for existing in existing_entries:
                 if existing.name in {".git", "AGENTS.md"}:
                     continue
@@ -1962,7 +1974,7 @@ class Runtime:
             updated = subprocess.run(
                 update_command,
                 cwd=staging,
-                env=self.toolchains.environment,
+                env=command_environment,
                 text=True,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.STDOUT,

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/lean_runtime/toolchains.py

@@ -92,6 +92,20 @@ class ToolchainManager:
         env["PATH"] = os.pathsep.join((str(elan_home / "bin"), env.get("PATH", "")))
         return env
 
+    def environment_for(self, toolchain: str) -> dict[str, str]:
+        """Return an environment whose nested tools use the selected full toolchain.
+
+        A directly invoked user Lake can spawn ``lake`` or ``lean`` again while
+        scaffolding. Put that already-verified toolchain ahead of private Elan
+        so those nested calls cannot bootstrap a differently spelled release.
+        """
+        env = self.environment
+        name = normalize_toolchain(toolchain)
+        full = self._full_toolchain_dir(name)
+        if (full / "bin" / "lean").is_file():
+            env["PATH"] = os.pathsep.join((str(full / "bin"), env.get("PATH", "")))
+        return env
+
     def elan_path(self, *, bootstrap: bool = True) -> Path:
         override = os.environ.get("LEAN_RUNTIME_ELAN")
         if override:

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/lean_runtime/verification.py

@@ -104,12 +104,20 @@ def _verify_capsule_state(environment: Environment) -> int:
     return verified
 
 
-def _probe(environment: Environment) -> None:
+def _probe(environment: Environment, *, offline: bool = False) -> None:
     """Probe the immutable compiled environment without asking Lake to resolve it."""
 
-    source = (
-        f"import {ROOT_MODULE}\n" if environment.lock.packages else "example : True := by trivial\n"
-    )
+    if environment.sparse:
+        origin = environment._record.get("origin")
+        retained = origin.get("modules") if isinstance(origin, dict) else None
+        modules = tuple(str(item) for item in retained) if isinstance(retained, list) else ()
+        source = f"import {modules[0]}\n" if modules else "example : True := by trivial\n"
+    else:
+        source = (
+            f"import {ROOT_MODULE}\n"
+            if environment.lock.packages
+            else "example : True := by trivial\n"
+        )
     result = environment.check(
         source,
         # The generated environment module itself is named ROOT_MODULE.  Giving
@@ -117,6 +125,7 @@ def _probe(environment: Environment) -> None:
         # correctly reject it as an import cycle.
         filename="LeanRuntimeVerification.lean",
         policy=ExecutionPolicy(timeout_seconds=300, max_output_bytes=2_000_000),
+        _allow_sparse_acquisition=not offline,
     )
     if not result.ok:
         raise EnvironmentError(
@@ -284,7 +293,7 @@ def verify_environment(
             raise EnvironmentError(
                 "offline verification requires the locked toolchain to be installed"
             )
-        _probe(environment)
+        _probe(environment, offline=offline)
         probe = VerificationCheck("lean_probe_passed", True)
     except EnvironmentError as exc:
         probe = VerificationCheck("probe_failed", False, details={"message": str(exc)})

{lean_runtime-4.0.0 → lean_runtime-4.0.1/lean_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 4.0.0
+Version: 4.0.1
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -194,6 +194,5 @@ interfaces for infrastructure code.
 - Logical Lean rejections exit 1; invalid/infrastructure invocations exit 2;
   publication failures retain their documented classified exit statuses.
 
-Documentation lives in [`docs/`](docs/index.md). Start with
-[`docs/getting-started.md`](docs/getting-started.md),
-[`docs/cli.md`](docs/cli.md), and [`docs/local-projects.md`](docs/local-projects.md).
+Documentation lives at
+[alerad.github.io/lean-runtime](https://alerad.github.io/lean-runtime/).

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/mkdocs.yml

@@ -7,10 +7,21 @@ copyright: Copyright © Alejandro Radisic
 
 theme:
   name: material
+  language: en
+  icon:
+    repo: fontawesome/brands/github
   features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
     - content.code.copy
+    - content.code.annotate
     - navigation.sections
     - navigation.top
+    - search.highlight
+    - search.suggest
+    - toc.follow
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
@@ -28,33 +39,55 @@ theme:
         name: Use light mode
 
 nav:
-  - Overview: index.md
-  - Getting started: getting-started.md
-  - Guides:
+  - Home: index.md
+  - Start here:
+      - Installation and first check: getting-started.md
       - Standalone Lean files: standalone-files.md
-      - Environments: environments.md
-      - Lake projects and shared dependencies: local-projects.md
+      - New and existing Lake projects: local-projects.md
+  - Workflows:
+      - Exact environments: environments.md
       - Portable copies and libraries: portable-copies.md
       - Publishing a Lean project: project-publishing.md
       - Ready-to-run programs: ready-programs.md
+  - Reference:
+      - Command line: cli.md
       - Python API: python-api.md
-      - CLI: cli.md
       - Execution captures: captures.md
       - Verify, compare, profile, and matrix: v1-precision.md
-      - V1 release case study: case-study-v1.md
   - Concepts:
       - Architecture: architecture.md
-      - Lake artifact-cache design: lake-artifact-cache-design.md
       - Trust and limitations: trust-and-limitations.md
-  - Development: development.md
+      - Lake artifact-cache design: lake-artifact-cache-design.md
+  - Project:
+      - Release case study: case-study-v1.md
+      - Development: development.md
+
+plugins:
+  - search
+
+extra_css:
+  - stylesheets/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/alerad/lean-runtime
+      name: Lean Runtime on GitHub
 
 markdown_extensions:
   - admonition
   - attr_list
+  - md_in_html
   - pymdownx.highlight:
       anchor_linenums: true
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.inlinehilite
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
   - toc:
       permalink: true
 

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lean-runtime"
-version = "4.0.0"
+version = "4.0.1"
 description = "Run Lean 4 proofs from Python or standalone files"
 readme = "README.md"
 requires-python = ">=3.10"

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/tests/test_environment_integration.py

@@ -309,6 +309,13 @@ def test_resolve_publish_and_reopen_offline_from_second_process(
         imported_check = imported.check(source)
         assert imported_check.ok
         assert imported_check.lock_id == lock.lock_id
+    # Offline verification must use only the retained projection. The fixture
+    # registry has stopped here, so any attempted sparse extension fails.
+    imported_verification = imported_runtime.verify("imported", offline=True)
+    assert imported_verification.ok
+    assert any(
+        item.code == "offline_retained_state_verified" for item in imported_verification.checks
+    )
     assert (runtime.store.executions / f"{first.execution_id}.json").is_file()
     assert (runtime.store.executions / f"{repeated.execution_id}.json").is_file()
     version = environment.execute(["lean", "--version"])

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/tests/test_projects.py

@@ -69,6 +69,7 @@ class InitProjectToolchains(ProjectToolchains):
             )
             script = (
                 "import pathlib,sys; root=pathlib.Path(sys.argv[1]); name=sys.argv[3]; "
+                "assert (root/'lean-toolchain').read_text().strip()==sys.argv[2]; "
                 "(root/'lean-toolchain').write_text(sys.argv[2]+'\\n'); "
                 "(root/'lakefile.toml').write_text(f'name = \\\"{name}\\\"\\n'); "
                 "(root/'.git').mkdir(); "

{lean_runtime-4.0.0 → lean_runtime-4.0.1}/tests/test_toolchains.py

@@ -112,6 +112,9 @@ def test_existing_user_elan_toolchain_is_reused_read_only(
         str(directory / "lean"),
         "--version",
     ]
+    execution_path = manager.environment_for(toolchain)["PATH"].split(os.pathsep)
+    assert execution_path[0] == str(directory)
+    assert execution_path[1] == str(manager.elan_home / "bin")
     monkeypatch.setattr(manager, "has_slim", lambda _name: True)
     with pytest.raises(ToolchainError, match="user-managed"):
         manager.prune_original(toolchain)