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

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

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 4.1.0 - 2026-08-19
+
+## 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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 4.0.0
+Version: 4.1.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -36,14 +36,35 @@ Dynamic: license-file
 
 # Lean Runtime
 
-Lean Runtime makes Lean projects and standalone proofs work without asking you
-to manage toolchains, dependency checkouts, exact environments, or caches.
+**Check the proof. Reuse everything else.**
 
 ```bash
 python -m pip install lean-runtime
 ```
 
-## The daily workflow
+Give Lean Runtime an ordinary file:
+
+```lean
+-- Main.lean
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```console
+$ lean-runtime check Main.lean
+✓ Main.lean accepted in 1.60s
+```
+
+No Lake project, dependency checkout, or toolchain setup required. Lean Runtime
+discovers and verifies the exact environment, then keeps it ready for offline
+reuse.
+
+[Get started](https://alerad.github.io/lean-runtime/getting-started/) ·
+[Read the documentation](https://alerad.github.io/lean-runtime/) ·
+[Explore the CLI](https://alerad.github.io/lean-runtime/cli/)
+
+## Start where you are
 
 Create a project:
 
@@ -77,7 +98,9 @@ lean-runtime check Main.lean
 ```
 
 The same command uses the nearest pinned Lake project when one exists and
-otherwise performs bounded exact-environment discovery. A file can carry its
+otherwise performs bounded exact-environment discovery. Automatic discovery
+uses retained or verified downloadable environments; building a missing
+candidate from source requires `--allow-source-build`. A file can carry its
 context in strict comment frontmatter:
 
 ```lean
@@ -194,6 +217,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.1.0}/README.md

@@ -1,13 +1,34 @@
 # Lean Runtime
 
-Lean Runtime makes Lean projects and standalone proofs work without asking you
-to manage toolchains, dependency checkouts, exact environments, or caches.
+**Check the proof. Reuse everything else.**
 
 ```bash
 python -m pip install lean-runtime
 ```
 
-## The daily workflow
+Give Lean Runtime an ordinary file:
+
+```lean
+-- Main.lean
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```console
+$ lean-runtime check Main.lean
+✓ Main.lean accepted in 1.60s
+```
+
+No Lake project, dependency checkout, or toolchain setup required. Lean Runtime
+discovers and verifies the exact environment, then keeps it ready for offline
+reuse.
+
+[Get started](https://alerad.github.io/lean-runtime/getting-started/) ·
+[Read the documentation](https://alerad.github.io/lean-runtime/) ·
+[Explore the CLI](https://alerad.github.io/lean-runtime/cli/)
+
+## Start where you are
 
 Create a project:
 
@@ -41,7 +62,9 @@ lean-runtime check Main.lean
 ```
 
 The same command uses the nearest pinned Lake project when one exists and
-otherwise performs bounded exact-environment discovery. A file can carry its
+otherwise performs bounded exact-environment discovery. Automatic discovery
+uses retained or verified downloadable environments; building a missing
+candidate from source requires `--allow-source-build`. A file can carry its
 context in strict comment frontmatter:
 
 ```lean
@@ -158,6 +181,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.1.0}/catalog/environments.toml

@@ -7,7 +7,6 @@ channel = "stable"
 lock = "locks/core-v4.32.2.lock.json"
 inventory_packages = []
 modules = ["Init", "Lean", "Std"]
-library_hints = []
 created_at = "2026-08-08T16:24:59Z"
 
 [[environment]]
@@ -16,7 +15,6 @@ channel = "stable"
 lock = "locks/mathlib-v4.32.2.lock.json"
 references = ["github:leanprover-community/mathlib4@v4.32.2"]
 inventory_packages = ["mathlib"]
-library_hints = []
 created_at = "2026-07-28T18:36:13+02:00"
 
 [[environment]]
@@ -25,7 +23,6 @@ channel = "stable"
 lock = "locks/mathlib-v4.33.0.lock.json"
 references = ["github:leanprover-community/mathlib4@v4.33.0"]
 inventory_packages = ["mathlib"]
-library_hints = []
 created_at = "2026-08-10T09:12:31Z"
 
 [[environment]]
@@ -34,7 +31,6 @@ channel = "stable"
 lock = "locks/mathlib-v4.31.0.lock.json"
 references = ["github:leanprover-community/mathlib4@v4.31.0"]
 inventory_packages = ["mathlib"]
-library_hints = []
 created_at = "2026-06-15T14:22:22Z"
 
 [[environment]]
@@ -43,7 +39,6 @@ channel = "stable"
 lock = "locks/mathlib-v4.30.0.lock.json"
 references = ["github:leanprover-community/mathlib4@v4.30.0"]
 inventory_packages = ["mathlib"]
-library_hints = []
 created_at = "2026-05-26T18:25:31Z"
 
 [[environment]]
@@ -55,7 +50,6 @@ references = [
   "github:leanprover-community/mathlib4@v4.30.0",
 ]
 inventory_packages = ["LeanCert", "mathlib"]
-library_hints = []
 created_at = "2026-06-14T03:06:27Z"
 
 [[environment]]
@@ -67,7 +61,6 @@ references = [
   "github:leanprover-community/mathlib4@v4.31.0",
 ]
 inventory_packages = ["LeanCert", "mathlib"]
-library_hints = []
 created_at = "2026-06-18T16:14:44Z"
 
 [[environment]]
@@ -79,7 +72,6 @@ references = [
   "github:leanprover-community/mathlib4@v4.32.2",
 ]
 inventory_packages = ["LeanCert", "mathlib"]
-library_hints = []
 created_at = "2026-08-01T10:49:16Z"
 
 [[environment]]
@@ -91,5 +83,4 @@ references = [
   "github:leanprover-community/mathlib4@v4.33.0",
 ]
 inventory_packages = ["LeanCert", "mathlib"]
-library_hints = []
 created_at = "2026-08-10T22:05:27Z"

lean_runtime-4.1.0/docs/concepts/context-selection.md

@@ -0,0 +1,54 @@
+# Context selection
+
+Every check runs inside one selected context. Context selection and compiler acceptance are separate decisions.
+
+## Precedence
+
+For a Lean file, Lean Runtime considers context sources in this order:
+
+1. An explicit command-line or Python API context
+2. Lean Runtime frontmatter in the file
+3. The nearest pinned Lake project
+4. Automatic catalog discovery
+
+If none can produce a context, the operation fails before Lean runs.
+
+## Explicit context
+
+```console
+lean-runtime check Main.lean --using mathlib@v4.33.0
+```
+
+An explicit context can identify a project, lock file, stored environment, toolchain, or package reference. Explicit input does not need discovery.
+
+## Frontmatter
+
+```lean
+-- /// lean-runtime
+-- toolchain = "leanprover/lean4:v4.33.0"
+-- ///
+example : 1 + 1 = 2 := by decide
+```
+
+Frontmatter travels with the source while remaining valid Lean comments.
+
+## Pinned project context
+
+A file beneath a Lake project uses the nearest project with both a pinned toolchain and manifest. Lean Runtime does not replace those version decisions during a normal project check.
+
+## Automatic discovery
+
+Discovery begins with declared source imports. The bundled catalog associates exact environments with module inventories. Plausible candidates are ordered under a bounded policy and checked in turn.
+
+Static analysis proposes candidates. It does not prove compatibility. A candidate is accepted only if Lean accepts the source inside that exact environment.
+
+Candidate count, compiler time, wall time, remote acquisition, offline mode, and source-build permission can bound the search. Reaching a bound can produce an inconclusive discovery result rather than a claim that no compatible environment exists.
+
+## Inspect the decision
+
+```console
+lean-runtime status Main.lean
+lean-runtime status Main.lean --json
+```
+
+`status` reports evidence and routing. A successful `check` reports compiler acceptance and execution provenance.

lean_runtime-4.1.0/docs/index.md

@@ -0,0 +1,118 @@
+---
+hide:
+  - navigation
+  - toc
+  - footer
+---
+
+<nav class="lr-topbar" aria-label="Main navigation">
+  <div class="lr-topbar-inner">
+    <a class="lr-wordmark" href="./">lean<span>-</span>runtime</a>
+    <span class="lr-version-chip">Lean 4 · Python 3.10+</span>
+    <div class="lr-topnav">
+      <a href="tutorial/">Start</a>
+      <a href="workflows/check-files/">Workflows</a>
+      <a href="concepts/context-selection/">Concepts</a>
+      <a href="reference/commands/">Reference</a>
+      <a href="trust/">Trust</a>
+      <a href="https://github.com/alerad/lean-runtime">GitHub</a>
+    </div>
+  </div>
+</nav>
+
+<section class="lr-hero" data-run-demo>
+  <div class="lr-hero-copy">
+    <p class="lr-eyebrow"><span aria-hidden="true">⊢</span> Compiler-backed Lean execution</p>
+    <h1>Check a Lean file in the environment it needs.</h1>
+    <p class="lr-lead">Lean Runtime resolves an exact toolchain and dependency context, runs Lean, and records what actually ran.</p>
+    <div class="lr-actions">
+      <a class="md-button md-button--primary" href="tutorial/">Run your first check</a>
+      <a class="md-button" href="concepts/context-selection/">How context is selected</a>
+    </div>
+    <div class="lr-install" aria-label="Install command">
+      <code>python -m pip install lean-runtime</code>
+      <button type="button" data-copy-install aria-label="Copy install command">Copy</button>
+    </div>
+    <p class="lr-platform-note">Python 3.10 or newer and Git are required. Automatic Elan bootstrap is available on macOS and Linux.</p>
+  </div>
+
+  <div class="lr-instrument" aria-label="Interactive Lean Runtime example">
+    <div class="lr-mode-tabs" role="tablist" aria-label="Execution context">
+      <button type="button" role="tab" aria-selected="true" data-demo-mode="automatic">Automatic</button>
+      <button type="button" role="tab" aria-selected="false" data-demo-mode="pinned">Pinned</button>
+      <button type="button" role="tab" aria-selected="false" data-demo-mode="project">Lake project</button>
+    </div>
+
+    <div class="lr-source-pane">
+      <div class="lr-pane-bar">
+        <span class="lr-pane-dot" aria-hidden="true"></span>
+        <span data-source-name>Primes.lean</span>
+        <span class="lr-pane-context" data-source-context>standalone file</span>
+      </div>
+      <pre data-source><code><span class="lr-kw">import</span> <mark>Mathlib.Data.Nat.Prime.Infinite</mark>
+
+<span class="lr-kw">example</span> : ∀ n : ℕ, ∃ p, n ≤ p ∧ p.Prime :=
+  Nat.exists_infinite_primes</code></pre>
+    </div>
+
+    <div class="lr-terminal-pane">
+      <div class="lr-pane-bar">
+        <span class="lr-pane-dot" aria-hidden="true"></span>
+        terminal
+        <span class="lr-pane-context" data-run-state>ready</span>
+      </div>
+      <div class="lr-terminal" data-terminal aria-live="polite"></div>
+    </div>
+
+    <div class="lr-demo-controls">
+      <button type="button" class="lr-replay" data-replay><span aria-hidden="true">↻</span> Replay</button>
+      <button type="button" class="lr-inspect-button" data-inspect aria-expanded="false">Inspect this run</button>
+    </div>
+
+    <div class="lr-run-record" data-run-record hidden>
+      <dl>
+        <div><dt>Context source</dt><dd data-record-context>automatic discovery</dd></div>
+        <div><dt>Toolchain</dt><dd><code>leanprover/lean4:v4.33.0</code></dd></div>
+        <div><dt>Environment</dt><dd><code>mathlib-v4.33.0</code></dd></div>
+        <div><dt>Verdict</dt><dd class="lr-accepted">accepted</dd></div>
+      </dl>
+      <p>The environment is proposed from source evidence. The verdict is produced by Lean.</p>
+    </div>
+  </div>
+</section>
+
+
+
+<section class="lr-workflows" aria-labelledby="workflows-title">
+  <div class="lr-section-heading">
+    <p class="lr-kicker">Workflows</p>
+    <h2 id="workflows-title">Use the entry point that matches your work.</h2>
+  </div>
+  <div class="lr-card-grid">
+    <article>
+      <p class="lr-card-label">Standalone file</p>
+      <h3>Bring a Lean source file</h3>
+      <pre><code>lean-runtime check Main.lean</code></pre>
+      <p>Use automatic discovery, a package reference, frontmatter, or an exact lock.</p>
+      <a href="workflows/check-files/">Check Lean files</a>
+    </article>
+    <article>
+      <p class="lr-card-label">Lake project</p>
+      <h3>Keep the project authoritative</h3>
+      <pre><code>lean-runtime adopt . --yes
+lean-runtime build</code></pre>
+      <p>The project keeps its pinned toolchain and manifest. Dependency storage and compatible artifacts can be reused.</p>
+      <a href="workflows/lake-projects/">Work with Lake projects</a>
+    </article>
+    <article>
+      <p class="lr-card-label">Exact and offline</p>
+      <h3>Record the environment</h3>
+      <pre><code>lean-runtime check Main.lean \
+  --lock-out environment.lock.json</code></pre>
+      <p>Reuse the resulting lock explicitly, including with network access disabled.</p>
+      <a href="workflows/check-files/#record-and-reuse-an-exact-lock">Use an exact lock</a>
+    </article>
+  </div>
+</section>
+
+

lean_runtime-4.1.0/docs/reference/commands.md

@@ -0,0 +1,67 @@
+# Commands
+
+This page summarizes the command surface. Run `lean-runtime COMMAND --help` for the installed version's complete arguments and options.
+
+## Daily workflows
+
+| Command | Purpose |
+| --- | --- |
+| `new NAME` | Create a Lean project. |
+| `adopt [PATH]` | Register existing Lake projects and prepare shared dependency storage. |
+| `check [PATH ...]` | Check a project or Lean source with inferred or explicit context. |
+| `watch FILE` | Recheck one project file when it changes. |
+| `build [TARGET ...]` | Build the current Lake project. |
+| `update [PATH]` | Apply the latest cataloged Mathlib/toolchain update; non-Mathlib projects are a no-op. |
+| `publish [PATH]` | Configure project publication. |
+
+## Inspection and maintenance
+
+| Command | Purpose |
+| --- | --- |
+| `status [SUBJECT]` | Explain the selected project or standalone context. |
+| `verify SUBJECT` | Verify a lock, environment, or artifact. |
+| `doctor` | Diagnose the local installation and configuration. |
+| `clean` | Preview and reclaim unused runtime storage. |
+| `replay CAPTURE` | Replay an execution capture. |
+| `completion SHELL` | Generate shell completion. |
+
+## Advanced namespaces
+
+| Namespace | Scope |
+| --- | --- |
+| `env` | Exact immutable environments and locks. |
+| `project` | Mutable project inspection, sharing, locks, and exports. |
+| `toolchain` | Toolchain installation, inspection, optimization, and publication. |
+| `storage` | Storage usage and verification. |
+| `program` | Ready-to-run program artifacts. |
+| `catalog` | Discovery catalog maintenance. |
+
+## Common check options
+
+```console
+lean-runtime check Main.lean --using CONTEXT
+lean-runtime check Main.lean --offline
+lean-runtime check Main.lean --json
+lean-runtime check Main.lean --timings
+lean-runtime check Main.lean --repeat 10
+```
+
+`--allow-source-build` permits standalone discovery to build an environment from source when no suitable acquired form is available.
+
+## Build cache control
+
+```console
+lean-runtime build
+lean-runtime build --no-cache
+```
+
+The default build may restore supported dependency artifacts before invoking Lake. `--no-cache` skips that restoration step.
+
+## Exit codes for check
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Lean accepted the source. |
+| `1` | Lean ran and rejected the source. |
+| `2` | Invocation, context, acquisition, or configuration failed. |
+| `130` | Interrupted. |

lean_runtime-4.1.0/docs/reference/python-api.md

@@ -0,0 +1,200 @@
+# Python API
+
+Set up one context, then check as many sources as you like. The expensive work
+happens on the first call; everything after it reuses the prepared environment.
+
+## Select a context
+
+`setup()` prepares one context and returns a handle:
+
+```python
+import lean_runtime as lean
+
+environment = lean.setup(["mathlib@v4.33.0"])
+locked = lean.setup(lock="environment.lock.json")
+existing = lean.setup(environment="research-stack")
+core = lean.setup(toolchain="v4.33.0")
+project = lean.setup(project="./my-project")
+```
+
+Exactly one of `deps`, `project`, `lock`, `environment`, or a bare `toolchain`
+is required. The same precedence applies here as on the command line; see
+[Context selection](../concepts/context-selection.md).
+
+Importing `lean_runtime` has no filesystem or network side effects. The default
+`Runtime` is created on the first operation. Pass `runtime=Runtime(...)` to any
+function for explicit configuration.
+
+## Check a source
+
+```python
+result = environment.check(source)
+result = environment.check_files(files, entrypoint="Main.lean")
+results = environment.check_many(sources, concurrency=8)
+```
+
+One-shot helpers route the same way:
+
+```python
+result = lean.check(source, deps=["mathlib@v4.33.0"])
+result = lean.check_file("./my-project/MyProject/Main.lean")
+result = lean.replay("execution.capture.json")
+```
+
+`replay()` requires an existing execution capture; the filename above is a
+placeholder for an artifact supplied by the caller or an execution backend.
+
+## Read the result
+
+Failed checks expose parsed diagnostics directly:
+
+```python
+for error in result.errors:
+    print(error.file, error.line, error.message)
+
+if result.first_error is not None:
+    print(result.first_error.location)
+```
+
+`errors` and `warnings` are severity-filtered views of `diagnostics`. Diagnostic
+extraction is best-effort; `stdout` and `stderr` remain authoritative.
+
+Scripts that prefer exceptions can use `result.raise_for_error()`, which raises
+`LeanCheckError` on rejection. Its `result` attribute retains diagnostics,
+output, environment and execution identities, and provenance.
+
+## Discover an environment
+
+`lean-runtime check FILE` discovers a context automatically for standalone
+files. The same bounded, compiler-authoritative search is available directly:
+
+```python
+from lean_runtime.discovery import Discovery, default_catalog
+
+discovery = Discovery(catalog=default_catalog())
+result = discovery.discover_and_check("""
+import Mathlib
+example : 2 + 2 = 4 := by norm_num
+""")
+result.raise_for_error()
+
+print(result.lock_id)
+print(result.environment_id)
+```
+
+Every successful result carries the exact `EnvironmentLock` Lean accepted. Pass
+that lock to ordinary operations to skip discovery on later runs.
+
+`outcome` and `completion` are reported separately, so a search stopped by a
+candidate, acquisition, or time limit reads as inconclusive rather than as an
+exhaustive rejection:
+
+```python
+if result.outcome == "inconclusive":
+    print(result.completion)  # candidate_limit | acquisition_limit | time_limit
+```
+
+Planning metadata narrows candidates. It never asserts compatibility.
+
+## Bound an execution
+
+```python
+from lean_runtime import ExecutionPolicy
+
+policy = ExecutionPolicy(
+    timeout_seconds=30,
+    max_output_bytes=1_000_000,
+    cpu_seconds=20,
+)
+result = environment.check(source, policy=policy)
+```
+
+Consult `result.provenance.enforced_policy_fields`: requested controls vary by
+backend and platform. The local backend rejects network isolation because it
+cannot enforce it. Memory limits are also backend-dependent. In particular,
+the local Linux backend currently applies `memory_mb` as a virtual-address-space
+limit, so Lean may need substantially more headroom than its resident memory
+suggests. Add that limit only after measuring the selected toolchain and backend.
+
+## Provenance
+
+`ExecutionResult` records the exit code, command, output, duration, phase
+timings, timeout/cancellation/truncation flags, diagnostics, and provenance.
+Provenance includes the `execution_id`, a stable `request_digest`, environment
+and lock identities, exact package commits and Git tree hashes, toolchain,
+platform, backend, policy, source digest, and start time.
+
+Mutable project results have no environment or lock identity. Their provenance
+instead records the canonical root, a workspace digest excluding `.git` and
+`.lake`, Lake configuration and manifest digests, and Git revision state.
+
+## Work with Lake projects
+
+```python
+project = runtime.project("./existing-project")
+project.check_file("./existing-project/MyLibrary/Main.lean")
+project.build(("MyLibrary",))
+```
+
+`build()` may restore dependency artifacts before invoking Lake. Opt out when
+measuring, or when a source-only build is required:
+
+```python
+project.build(("MyLibrary",), artifact_cache=False)
+```
+
+`runtime.project()` also accepts a contained file and resolves the nearest
+pinned Lake root. See [Work with Lake projects](../workflows/lake-projects.md).
+
+## Cancel work in flight
+
+```python
+job = environment.start_check(source)
+if no_longer_needed:
+    job.cancel()
+result = job.result()
+```
+
+`cancel()` returns `False` once the job has completed. Cancellation is
+cooperative and terminates the local child process.
+
+The asyncio helpers preserve that behaviour:
+
+```python
+result = await environment.check_async(source)
+results = await environment.check_many_async(sources, concurrency=8)
+```
+
+Synchronous `setup()`, `check()`, and `Runtime.prepare()` accept a
+`threading.Event` through `cancel=`, which interrupts toolchain installation,
+Lake resolution, and environment builds.
+
+## Keep a tool alive
+
+`spawn_interactive()` holds one process open inside a disposable instance and
+exposes line-buffered UTF-8 pipes, for REPLs, language servers, and NDJSON
+bridges where startup cost should be paid once:
+
+```python
+with environment.spawn_interactive(["lake", "exe", "lean_bridge"]) as session:
+    response = session.request_json({"id": 1, "method": "get_info", "params": {}})
+
+result = session.close()
+```
+
+`close()` is idempotent, closes stdin first so cooperative servers exit on EOF,
+then terminates the process group if needed. `send_line()`, `read_line()`,
+`request_line()`, and `request_json()` are locked so concurrent callers cannot
+interleave protocol frames. `lean_bridge` is an example project executable, not
+a program bundled with Lean Runtime; replace it with a line-oriented tool provided
+by the selected environment.
+
+## Observe progress
+
+```python
+runtime = Runtime(on_event=lambda event: print(event.kind, event.data))
+```
+
+Events are typed `RuntimeEvent` values, not parsed log lines. They cover
+toolchain readiness, Lake resolution, source locking, artifact restoration,
+builds, publication, and environment reuse.