lean-runtime 4.2.0__tar.gz → 4.22.0__tar.gz

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 4.22.0 - 2026-08-23
+
+## 4.21.0 - 2026-08-23
+
 ## 4.2.0 - 2026-08-23
 
 - Add a scheduled catalog-update workflow that detects a new stable Mathlib

{lean_runtime-4.2.0/lean_runtime.egg-info → lean_runtime-4.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 4.2.0
+Version: 4.22.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -53,16 +53,15 @@ example : 2 + 2 = 4 := by norm_num
 
 ```console
 $ lean-runtime check Main.lean
-✓ Main.lean accepted in 2.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/) ·
+[Get started](https://alerad.github.io/lean-runtime/tutorial/) ·
 [Read the documentation](https://alerad.github.io/lean-runtime/) ·
-[Explore the CLI](https://alerad.github.io/lean-runtime/cli/)
+[Explore the CLI](https://alerad.github.io/lean-runtime/reference/commands/)
 
 ## Start where you are
 
@@ -100,8 +99,15 @@ lean-runtime check Main.lean
 The same command uses the nearest pinned Lake project when one exists and
 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:
+candidate from source requires `--allow-source-build`.
+
+Record the environment only when the result must be reproduced elsewhere:
+
+```bash
+lean-runtime check Main.lean --write-lock environment.lock.json
+```
+
+A file can instead carry an explicit context in strict comment frontmatter:
 
 ```lean
 -- /// lean-runtime

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/README.md

@@ -17,16 +17,15 @@ example : 2 + 2 = 4 := by norm_num
 
 ```console
 $ lean-runtime check Main.lean
-✓ Main.lean accepted in 2.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/) ·
+[Get started](https://alerad.github.io/lean-runtime/tutorial/) ·
 [Read the documentation](https://alerad.github.io/lean-runtime/) ·
-[Explore the CLI](https://alerad.github.io/lean-runtime/cli/)
+[Explore the CLI](https://alerad.github.io/lean-runtime/reference/commands/)
 
 ## Start where you are
 
@@ -64,8 +63,15 @@ lean-runtime check Main.lean
 The same command uses the nearest pinned Lake project when one exists and
 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:
+candidate from source requires `--allow-source-build`.
+
+Record the environment only when the result must be reproduced elsewhere:
+
+```bash
+lean-runtime check Main.lean --write-lock environment.lock.json
+```
+
+A file can instead carry an explicit context in strict comment frontmatter:
 
 ```lean
 -- /// lean-runtime

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/concepts/context-selection.md

@@ -2,6 +2,10 @@
 
 Every check runs inside one selected context. Context selection and compiler acceptance are separate decisions.
 
+For ordinary standalone checks, let Lean Runtime discover the context. Explicit
+context is an override for reproducibility, compatibility testing, or a request
+that specifically names a release.
+
 ## Precedence
 
 For a Lean file, Lean Runtime considers context sources in this order:

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/index.md

@@ -93,7 +93,7 @@ hide:
       <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>
+      <p>Lean Runtime discovers a plausible exact environment and accepts it only when Lean accepts the file.</p>
       <a href="workflows/check-files/">Check Lean files</a>
     </article>
     <article>
@@ -108,11 +108,10 @@ lean-runtime build</code></pre>
       <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>
+  --write-lock 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.2.0 → lean_runtime-4.22.0}/docs/reference/commands.md

@@ -32,23 +32,28 @@ This page summarizes the command surface. Run `lean-runtime COMMAND --help` for
 | `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. |
+| `storage` | Storage usage and verification; see [Storage](storage.md). |
 | `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
 lean-runtime check Main.lean --json
 lean-runtime check Main.lean --timings
 lean-runtime check Main.lean --repeat 10
+lean-runtime check Main.lean --write-lock environment.lock.json
 lean-runtime check - --using leanprover/lean4:v4.33.0
 ```
 
 `-` reads Lean source from standard input and requires an explicit context.
 
+Automatic discovery is the normal standalone workflow. `--using CONTEXT`
+overrides it when a package release, lock, toolchain, environment, or project is
+specifically required. `--offline` prevents acquisition and therefore needs the
+selected content to be retained locally.
+
 `--allow-source-build` permits standalone discovery to build an environment from source when no suitable acquired form is available.
 
 ## Build cache control

lean_runtime-4.22.0/docs/reference/python-advanced.md

@@ -0,0 +1,69 @@
+# Advanced Python workflows
+
+These APIs are useful for services and integrations. Ordinary scripts can use
+the synchronous API in [Python API](python-api.md).
+
+## Cancel work in flight
+
+```python
+import lean_runtime as lean
+
+environment = lean.setup(toolchain="v4.33.0")
+job = environment.start_check("example : True := trivial")
+cancelled = job.cancel()
+result = job.result()
+```
+
+`cancel()` returns `False` once the job has completed. Cancellation is
+cooperative and terminates the local child process.
+
+## Use asyncio
+
+```python
+import asyncio
+import lean_runtime as lean
+
+
+async def main() -> None:
+    environment = lean.setup(toolchain="v4.33.0")
+    source = "example : True := trivial"
+    result = await environment.check_async(source)
+    results = await environment.check_many_async([source, source], concurrency=2)
+    assert result.ok and all(item.ok for item in results)
+
+
+asyncio.run(main())
+```
+
+Synchronous `setup()`, `check()`, and `Runtime.prepare()` also accept a
+`threading.Event` through `cancel=`.
+
+## Replay a capture
+
+```python
+import lean_runtime as lean
+
+result = lean.replay("execution.capture.json")
+```
+
+The path must identify an execution capture created or supplied by the caller;
+Lean Runtime does not bundle the placeholder file above.
+
+## Keep a process alive
+
+`spawn_interactive()` exposes line-buffered UTF-8 pipes for a line-oriented tool
+provided by the selected environment:
+
+```python
+import lean_runtime as lean
+
+environment = lean.setup(["mathlib@v4.33.0"])
+with environment.spawn_interactive(["lake", "exe", "lean_bridge"]) as session:
+    response = session.request_json({"id": 1, "method": "get_info", "params": {}})
+
+result = session.close()
+```
+
+`lean_bridge` is an example project executable, not a program bundled with Lean
+Runtime. `close()` is idempotent and terminates the process group when the tool
+does not exit after its input closes.

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/reference/python-api.md

@@ -11,9 +11,10 @@ happens on the first call; everything after it reuses the prepared environment.
 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")
+
+# Alternatives when these caller-provided contexts already exist:
+locked = lean.setup(lock="environment.lock.json")
 project = lean.setup(project="./my-project")
 ```
 
@@ -28,6 +29,16 @@ function for explicit configuration.
 ## Check a source
 
 ```python
+source = """\
+import Mathlib
+example : 2 + 2 = 4 := by norm_num
+"""
+files = {
+    "Helper.lean": "def answer := 42\n",
+    "Main.lean": "import Helper\nexample : answer = 42 := rfl\n",
+}
+sources = [source, "example : True := trivial"]
+
 result = environment.check(source)
 result = environment.check_files(files, entrypoint="Main.lean")
 results = environment.check_many(sources, concurrency=8)
@@ -37,13 +48,9 @@ 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")
+result = lean.check_file("./my-project/MyProject/Basic.lean")
 ```
 
-`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:
@@ -131,6 +138,7 @@ instead records the canonical root, a workspace digest excluding `.git` and
 ## Work with Lake projects
 
 ```python
+runtime = lean.Runtime()
 project = runtime.project("./existing-project")
 project.check_file("./existing-project/MyLibrary/Main.lean")
 project.build(("MyLibrary",))
@@ -146,55 +154,15 @@ 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))
+runtime = lean.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.
+
+Cancellation, asyncio, replay, and persistent interactive processes are covered
+in [Advanced Python workflows](python-advanced.md).

lean_runtime-4.22.0/docs/reference/storage.md

@@ -0,0 +1,54 @@
+# Storage
+
+Lean Runtime retains exact toolchains, sources, environments, and compiled
+artifacts so later checks can run without repeating acquisition or builds.
+
+## Inspect usage
+
+```console
+lean-runtime storage usage
+```
+
+The report distinguishes two totals:
+
+- **Materialized** sums the logical size of every retained category. A file
+  hard-linked from the shared CAS into an environment appears in both category
+  rows.
+- **Allocated** counts hard-linked files once and uses allocated filesystem
+  blocks. It remains an estimate because filesystems such as APFS can share
+  copy-on-write blocks without exposing that relationship through ordinary file
+  metadata.
+
+Consequently, materialized size is useful for understanding retained content
+but is not a claim about unique physical disk consumption.
+
+`lean-runtime storage verify` rebuilds the storage ledger by scanning the whole
+store. It can take significant time on a large cache; ordinary usage reads the
+cached ledger when its fingerprint is current.
+
+## Scratch workspaces
+
+Checks, builds, dependency resolution, and interactive programs use disposable
+workspaces. Normal completion removes them. A workspace is considered abandoned
+when it is old enough and no process holds its ownership lease.
+
+Legacy workspaces from releases that predate ownership markers are retained for
+at least 24 hours before `doctor --yes` removes them.
+
+## Reclaim space
+
+Preview cleanup first:
+
+```console
+lean-runtime clean --dry-run
+```
+
+Apply the displayed plan explicitly:
+
+```console
+lean-runtime clean --yes
+```
+
+Named, recent, and in-use environments are retained. Add `--all` only when the
+download cache should also be considered. Shared project packages remain
+available for project reuse.

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/trust.md

@@ -27,11 +27,14 @@ Lake packages and build scripts can execute code during acquisition or compilati
 ```console
 lean-runtime verify environment.lock.json
 lean-runtime verify ENVIRONMENT
-lean-runtime storage verify
 ```
 
 Use `--offline` when verification must not contact remote services. Use `verify --rebuild` when independent reconstruction is required and permitted.
 
+`lean-runtime storage verify` performs a deeper scan of the entire local store.
+It is a maintenance operation and can take significant time on a large cache;
+see [Storage](reference/storage.md).
+
 ## Diagnose the local runtime
 
 ```console

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/tutorial.md

@@ -26,13 +26,14 @@ Create `Basic.lean`:
 example : 1 + 1 = 2 := by decide
 ```
 
-Choose a toolchain explicitly for this first check:
+Check it directly:
 
 ```console
-lean-runtime check Basic.lean --using leanprover/lean4:v4.33.0
+lean-runtime check Basic.lean
 ```
 
-Exit code `0` means Lean accepted the file.
+Lean Runtime selects a plausible catalog context and runs Lean. Exit code `0`
+means Lean accepted the file in the reported context.
 
 ## Check a file that imports Mathlib
 
@@ -51,63 +52,51 @@ Run the check without specifying a context:
 lean-runtime check Primes.lean
 ```
 
-When no explicit context, frontmatter, or pinned Lake project applies, Lean Runtime uses the imports as evidence for automatic discovery. It tries exact catalog environments within a bounded policy. A candidate succeeds only when Lean accepts the source in that environment.
+For a standalone file, Lean Runtime uses imports as evidence for automatic
+discovery. It tries exact catalog environments within a bounded policy. A
+candidate succeeds only when Lean accepts the source in that environment.
 
 The first run may install a toolchain and acquire environment content. Later checks reuse retained content.
 
-## Inspect context selection
+## Record an exact lock
 
-`status` reports routing information without running Lean:
+Write the environment used by a successful check:
 
 ```console
-lean-runtime status Primes.lean
+lean-runtime check Primes.lean --write-lock primes.lock.json
 ```
 
-The report includes the subject, declared imports, matching candidates, and the candidate currently planned first. It does not establish compiler acceptance.
-
-## Specify a package release
-
-Use `--using` when the context is part of the request:
+Use the lock on a later run:
 
 ```console
-lean-runtime check Primes.lean --using mathlib@v4.33.0
+lean-runtime check Primes.lean --using primes.lock.json
 ```
 
-The same requirement can be stored in the file:
-
-```lean
--- /// lean-runtime
--- requires = ["mathlib@v4.33.0"]
--- ///
-import Mathlib.Data.Nat.Prime.Infinite
+After the required toolchain and environment content are available locally, the same check can prohibit network access:
 
-example : ∀ n : ℕ, ∃ p, n ≤ p ∧ p.Prime :=
-  Nat.exists_infinite_primes
+```console
+lean-runtime check Primes.lean --using primes.lock.json --offline
 ```
 
-Command-line context and frontmatter are explicit alternatives. Conflicting explicit context is rejected before acquisition.
+Offline mode does not acquire missing remote content. Missing requirements produce an infrastructure failure rather than a Lean rejection.
 
-## Record an exact lock
+## Troubleshoot or override selection
 
-Write the environment used by a successful check:
+`status` previews routing without running Lean:
 
 ```console
-lean-runtime check Primes.lean --lock-out primes.lock.json
-```
-
-Use the lock on a later run:
-
-```console
-lean-runtime check Primes.lean --using primes.lock.json
+lean-runtime status Primes.lean
 ```
 
-After the required toolchain and environment content are available locally, the same check can prohibit network access:
+Most checks should rely on discovery. Use `--using` only when a particular
+release or context is part of the request:
 
 ```console
-lean-runtime check Primes.lean --using primes.lock.json --offline
+lean-runtime check Primes.lean --using mathlib@v4.33.0
 ```
 
-Offline mode does not acquire missing remote content. Missing requirements produce an infrastructure failure rather than a Lean rejection.
+See [Context selection](concepts/context-selection.md) for frontmatter, project
+precedence, and other explicit context forms.
 
 ## Interpret the result
 

{lean_runtime-4.2.0 → lean_runtime-4.22.0}/docs/workflows/check-files.md

@@ -16,44 +16,10 @@ Preview the routing decision without running Lean:
 lean-runtime status Main.lean
 ```
 
-## Select a context explicitly
-
-`--using` accepts several kinds of context:
-
-```console
-lean-runtime check Main.lean --using mathlib@v4.33.0
-lean-runtime check Main.lean --using environment.lock.json
-lean-runtime check Main.lean --using leanprover/lean4:v4.33.0
-lean-runtime check Main.lean --using ./some-project
-```
-
-Package references resolve a published package release. Lock files identify an exact dependency graph. Toolchain references provide a core Lean context. Project paths use the project toolchain and manifest; the file must live inside that project's root.
-
-## Check standard input
-
-Pass `-` as the input. Standard input carries no filename evidence, so an explicit context is required:
-
-```console
-echo 'example : True := trivial' | lean-runtime check - --using leanprover/lean4:v4.33.0
-```
-
-## Put context in the file
-
-Frontmatter must appear before Lean source and each line remains a Lean comment:
-
-```lean
--- /// lean-runtime
--- requires = ["mathlib@v4.33.0"]
--- ///
-import Mathlib
-```
-
-Supported fields are `requires`, `toolchain`, and `lock`. A lock already identifies the complete environment, so `lock` cannot be combined with `requires` or `toolchain`.
-
 ## Record and reuse an exact lock
 
 ```console
-lean-runtime check Main.lean --lock-out environment.lock.json
+lean-runtime check Main.lean --write-lock environment.lock.json
 lean-runtime check Main.lean --using environment.lock.json
 ```
 
@@ -91,6 +57,41 @@ lean-runtime check Main.lean --json
 
 The structured result distinguishes compiler rejection from context or acquisition failure and includes execution metadata.
 
+## Override discovery
+
+Use `--using` only when a particular context is part of the request:
+
+```console
+lean-runtime check Main.lean --using mathlib@v4.33.0
+lean-runtime check Main.lean --using environment.lock.json
+lean-runtime check Main.lean --using leanprover/lean4:v4.33.0
+lean-runtime check some-project/MyProject/Main.lean --using ./some-project
+```
+
+Package references resolve a published release. Lock files identify an exact
+dependency graph. Toolchain references provide a core Lean context. A file
+checked in a project context must live inside that project.
+
+Frontmatter can carry the same requirement with the source:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.33.0"]
+-- ///
+import Mathlib
+```
+
+Supported fields are `requires`, `toolchain`, and `lock`. A lock cannot be
+combined with `requires` or `toolchain`.
+
+## Check standard input
+
+Standard input has no filename evidence, so it requires an explicit context:
+
+```console
+echo 'example : True := trivial' | lean-runtime check - --using leanprover/lean4:v4.33.0
+```
+
 ## Watch a project file
 
 The current watch workflow requires one file inside a pinned Lake project: