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

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

@@ -2,6 +2,35 @@
 
 ## 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`,
+  `adopt`, universal `check`, `watch`, `build`, `update`, `publish`, `status`,
+  `verify`, `doctor`, and `clean`.
+- Remove the `lean-run` and `lean-runtime-catalog` entry points and all v3
+  compatibility spellings. Exact environment operations now live under `env`;
+  advanced project operations use `project info/scan/share/unshare/lock/export`.
+- Merge standalone discovery into `lean-runtime check`. A single `--using`
+  override replaces the old project, package, lock, environment, and toolchain
+  context flags.
+- Make cwd the implicit subject for project commands. Adoption detects whether
+  its subject is one Lake project or a tree, previews the storage transition,
+  confirms interactively, and preserves atomic rollback.
+- Detect compatible user Elan toolchains automatically and use them read-only.
+  Missing toolchains are still installed in Lean Runtime's private Elan home,
+  and optimization never prunes a user-managed installation.
+- Make cleanup, adoption, updates, publication setup, and safe doctor repairs
+  guided operations. Automation uses `--yes`; inspection uses `--dry-run`.
+
 ## 3.0.3 - 2026-08-18
 
 - Give sparse-environment and slim-toolchain downloads independent progress

lean_runtime-4.0.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: lean-runtime
+Version: 4.0.1
+Summary: Run Lean 4 proofs from Python or standalone files
+Author: Alejandro Radisic
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/alerad/lean-runtime
+Project-URL: Documentation, https://alerad.github.io/lean-runtime/
+Project-URL: Repository, https://github.com/alerad/lean-runtime.git
+Project-URL: Issues, https://github.com/alerad/lean-runtime/issues
+Project-URL: Changelog, https://github.com/alerad/lean-runtime/blob/main/CHANGELOG.md
+Keywords: lean4,theorem-prover,formal-verification,toolchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Requires-Dist: zstandard<1,>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: tomli>=2; extra == "dev"
+Requires-Dist: jsonschema>=4.23; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+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.
+
+```bash
+python -m pip install lean-runtime
+```
+
+## The daily workflow
+
+Create a project:
+
+```bash
+lean-runtime new MyProof
+cd MyProof
+lean-runtime check
+lean-runtime build
+```
+
+Use an existing pinned Lake project from its directory:
+
+```bash
+lean-runtime check
+lean-runtime adopt
+```
+
+`adopt` verifies the existing exact dependency graph, previews reuse and disk
+recovery, asks for confirmation, and swaps dependency links atomically. It does
+not change `lean-toolchain` or `lake-manifest.json`. Passing a directory that
+contains several projects discovers them automatically:
+
+```bash
+lean-runtime adopt ~/research
+```
+
+Check a standalone source file:
+
+```bash
+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
+context in strict comment frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.33.0"]
+-- ///
+
+import Mathlib
+example : 2 + 2 = 4 := by norm_num
+```
+
+When inference needs an override, there is one spelling:
+
+```bash
+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 research-stack
+lean-runtime check Main.lean --using lean:v4.33.0
+lean-runtime check Main.lean --using ~/proofs/MyProject
+```
+
+Typed `package:`, `lock:`, `env:`, `toolchain:`, and `project:` prefixes resolve
+rare ambiguities. Persistent store, registry, and trust policy belongs in
+environment configuration rather than everyday command lines.
+
+## Commands
+
+The normal surface is deliberately small:
+
+```text
+new NAME       create a project
+adopt [PATH]   share dependencies from existing project(s)
+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 safe project update
+publish        configure verified project publication
+status [PATH]  explain the selected project or environment
+verify SUBJECT verify an exact artifact
+doctor         diagnose and offer safe repairs
+clean          preview and reclaim unused storage
+```
+
+Project commands use the current directory when no path is supplied. Guided
+mutations show their plan and ask before changing anything; automation passes
+`--yes`, and inspection-only calls pass `--dry-run`.
+
+Persistent registry, availability, store, and publisher-trust policy belongs
+in `~/.config/lean-runtime/config.toml`; the nearest project's
+`lean-runtime.toml` can override it. Daily commands therefore normally need no
+configuration flags.
+
+Exact and operator workflows live under noun namespaces:
+
+```text
+env       list · info · lock · acquire · diff · export · import
+project   info · scan · share · unshare · lock · export
+program   create · run · info · acquire · export · import · publish
+toolchain list · info · install · optimize
+storage   usage · verify
+catalog   catalog maintenance
+```
+
+There are no v3 command aliases. `run`, `init`, `prepare`, `open`, `download`,
+`environments`, `inspect`, `compare`, `copy`, `finalize`, `lean-run`, and
+`lean-runtime-catalog` were removed in 4.0.
+
+## Existing Elan installations
+
+Lean Runtime automatically reuses an exact compatible toolchain already
+installed by the user's Elan. This access is read-only: it never changes the
+user's default, installs into the user's Elan home, or removes user toolchains.
+Missing toolchains and downloadable slim checking runtimes remain isolated in
+Lean Runtime's private store. `lean-runtime status` and `doctor` expose the
+choice when it matters.
+
+## Exact environments
+
+```bash
+lean-runtime env lock environment.toml --output environment.lock.json
+lean-runtime env acquire environment.lock.json --name research-stack
+lean-runtime env info research-stack
+lean-runtime env diff previous.lock.json environment.lock.json
+lean-runtime env export research-stack --output research-stack.lean-environment
+lean-runtime env import research-stack.lean-environment --name imported-stack
+```
+
+Locks are canonical and content-addressed. Full environments preserve source;
+downloaded sparse capsules project only verified import closures and keep the
+same environment identity as their projection grows.
+
+## Python
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(deps=["mathlib@v4.33.0"])
+result = env.check("import Mathlib\nexample : 2 + 2 = 4 := by norm_num\n")
+result.raise_for_error()
+```
+
+The Python API retains the explicit `Runtime`, `EnvironmentSpec`,
+`EnvironmentLock`, project, capture, program, cancellation, and verification
+interfaces for infrastructure code.
+
+## Guarantees and limits
+
+- Exact Git commits, trees, locks, toolchains, platform identities, and artifact
+  digests are verified before an environment becomes ready.
+- Acquisitions and project sharing are staged, probed, and published atomically.
+- User project metadata and user Elan state are not silently rewritten.
+- The local execution backend enforces supported resource limits but is not a
+  network sandbox; unsupported isolation requests fail explicitly.
+- Logical Lean rejections exit 1; invalid/infrastructure invocations exit 2;
+  publication failures retain their documented classified exit statuses.
+
+Documentation lives at
+[alerad.github.io/lean-runtime](https://alerad.github.io/lean-runtime/).

lean_runtime-4.0.1/README.md

@@ -0,0 +1,162 @@
+# Lean Runtime
+
+Lean Runtime makes Lean projects and standalone proofs work without asking you
+to manage toolchains, dependency checkouts, exact environments, or caches.
+
+```bash
+python -m pip install lean-runtime
+```
+
+## The daily workflow
+
+Create a project:
+
+```bash
+lean-runtime new MyProof
+cd MyProof
+lean-runtime check
+lean-runtime build
+```
+
+Use an existing pinned Lake project from its directory:
+
+```bash
+lean-runtime check
+lean-runtime adopt
+```
+
+`adopt` verifies the existing exact dependency graph, previews reuse and disk
+recovery, asks for confirmation, and swaps dependency links atomically. It does
+not change `lean-toolchain` or `lake-manifest.json`. Passing a directory that
+contains several projects discovers them automatically:
+
+```bash
+lean-runtime adopt ~/research
+```
+
+Check a standalone source file:
+
+```bash
+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
+context in strict comment frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.33.0"]
+-- ///
+
+import Mathlib
+example : 2 + 2 = 4 := by norm_num
+```
+
+When inference needs an override, there is one spelling:
+
+```bash
+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 research-stack
+lean-runtime check Main.lean --using lean:v4.33.0
+lean-runtime check Main.lean --using ~/proofs/MyProject
+```
+
+Typed `package:`, `lock:`, `env:`, `toolchain:`, and `project:` prefixes resolve
+rare ambiguities. Persistent store, registry, and trust policy belongs in
+environment configuration rather than everyday command lines.
+
+## Commands
+
+The normal surface is deliberately small:
+
+```text
+new NAME       create a project
+adopt [PATH]   share dependencies from existing project(s)
+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 safe project update
+publish        configure verified project publication
+status [PATH]  explain the selected project or environment
+verify SUBJECT verify an exact artifact
+doctor         diagnose and offer safe repairs
+clean          preview and reclaim unused storage
+```
+
+Project commands use the current directory when no path is supplied. Guided
+mutations show their plan and ask before changing anything; automation passes
+`--yes`, and inspection-only calls pass `--dry-run`.
+
+Persistent registry, availability, store, and publisher-trust policy belongs
+in `~/.config/lean-runtime/config.toml`; the nearest project's
+`lean-runtime.toml` can override it. Daily commands therefore normally need no
+configuration flags.
+
+Exact and operator workflows live under noun namespaces:
+
+```text
+env       list · info · lock · acquire · diff · export · import
+project   info · scan · share · unshare · lock · export
+program   create · run · info · acquire · export · import · publish
+toolchain list · info · install · optimize
+storage   usage · verify
+catalog   catalog maintenance
+```
+
+There are no v3 command aliases. `run`, `init`, `prepare`, `open`, `download`,
+`environments`, `inspect`, `compare`, `copy`, `finalize`, `lean-run`, and
+`lean-runtime-catalog` were removed in 4.0.
+
+## Existing Elan installations
+
+Lean Runtime automatically reuses an exact compatible toolchain already
+installed by the user's Elan. This access is read-only: it never changes the
+user's default, installs into the user's Elan home, or removes user toolchains.
+Missing toolchains and downloadable slim checking runtimes remain isolated in
+Lean Runtime's private store. `lean-runtime status` and `doctor` expose the
+choice when it matters.
+
+## Exact environments
+
+```bash
+lean-runtime env lock environment.toml --output environment.lock.json
+lean-runtime env acquire environment.lock.json --name research-stack
+lean-runtime env info research-stack
+lean-runtime env diff previous.lock.json environment.lock.json
+lean-runtime env export research-stack --output research-stack.lean-environment
+lean-runtime env import research-stack.lean-environment --name imported-stack
+```
+
+Locks are canonical and content-addressed. Full environments preserve source;
+downloaded sparse capsules project only verified import closures and keep the
+same environment identity as their projection grows.
+
+## Python
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(deps=["mathlib@v4.33.0"])
+result = env.check("import Mathlib\nexample : 2 + 2 = 4 := by norm_num\n")
+result.raise_for_error()
+```
+
+The Python API retains the explicit `Runtime`, `EnvironmentSpec`,
+`EnvironmentLock`, project, capture, program, cancellation, and verification
+interfaces for infrastructure code.
+
+## Guarantees and limits
+
+- Exact Git commits, trees, locks, toolchains, platform identities, and artifact
+  digests are verified before an environment becomes ready.
+- Acquisitions and project sharing are staged, probed, and published atomically.
+- User project metadata and user Elan state are not silently rewritten.
+- The local execution backend enforces supported resource limits but is not a
+  network sandbox; unsupported isolation requests fail explicitly.
+- Logical Lean rejections exit 1; invalid/infrastructure invocations exit 2;
+  publication failures retain their documented classified exit statuses.
+
+Documentation lives at
+[alerad.github.io/lean-runtime](https://alerad.github.io/lean-runtime/).

lean_runtime-4.0.1/docs/cli.md

@@ -0,0 +1,111 @@
+# Command line
+
+Lean Runtime 4 exposes intentions, not its storage implementation.
+
+## Daily commands
+
+```text
+lean-runtime new NAME
+lean-runtime adopt [PATH]
+lean-runtime check [PATH...]
+lean-runtime watch FILE
+lean-runtime build [TARGET...]
+lean-runtime update
+lean-runtime publish
+```
+
+All project commands use the current directory by default. `check` selects the
+nearest pinned Lake project or discovers an exact standalone environment. It
+accepts files, directories, stdin (`-`), or no path for the current project.
+
+Use `--using CONTEXT` only to override inference. It accepts a project path,
+lock path, environment name, Lean version, or package reference. Prefixes
+`project:`, `lock:`, `env:`, `toolchain:`, and `package:` disambiguate names.
+
+```bash
+lean-runtime check Main.lean --using mathlib@v4.33.0
+lean-runtime check Main.lean --using environment.lock.json --offline
+lean-runtime check Main.lean --using research-stack
+```
+
+`watch` is the file-watching operation. Repeated performance samples remain a
+variant of checking:
+
+```bash
+lean-runtime watch MyProject/Basic.lean
+lean-runtime check MyProject/Basic.lean --repeat 5
+lean-runtime check Main.lean --matrix compatibility.toml
+```
+
+## Guided mutation
+
+`new`, `adopt`, `update`, `publish`, `doctor`, and `clean` print what they will
+do and confirm in a terminal. `--yes` is the non-interactive spelling.
+`--dry-run` requests an inspection-only adoption, update, share/unshare, or
+cleanup.
+
+## Persistent configuration
+
+Machine policy belongs in `~/.config/lean-runtime/config.toml` (or the file
+named by `LEAN_RUNTIME_CONFIG`). A nearest project `lean-runtime.toml` may
+override it. Command-line values are temporary overrides.
+
+```toml
+[runtime]
+home = "/var/lib/lean-runtime"
+libraries = ["ghcr.io/example/lean-runtime-cache"]
+availability = "auto" # auto, required, or local
+
+[trust]
+publisher_verification = "required" # required or ignore
+trusted_publisher = "https://github.com/example/repo/.github/workflows/publish.yml@refs/heads/main"
+trusted_issuer = "https://token.actions.githubusercontent.com"
+verification_tool = "cosign"
+```
+
+The project file can keep its existing adoption metadata at the top level;
+only the `[runtime]` and `[trust]` tables participate in CLI configuration.
+
+## Inspection
+
+```bash
+lean-runtime status
+lean-runtime status Main.lean
+lean-runtime verify SUBJECT
+lean-runtime doctor
+lean-runtime clean
+```
+
+## Advanced namespaces
+
+```text
+env list
+env info NAME
+env lock SPEC
+env acquire LOCK
+env diff A B
+env export NAME --output FILE
+env import FILE
+env publish / env finalize
+
+project info / scan / share / unshare / lock / export
+program create / run / info / export / import / acquire / publish / finalize
+toolchain list / info / install / optimize / publish / finalize
+storage usage / verify
+catalog build
+```
+
+`replay` and `completion` remain top-level reproducibility utilities.
+
+There are no compatibility aliases for the v3 surface. In particular, `run`,
+`init`, `prepare`, `open`, `download`, `environments`, `inspect`, `compare`,
+`copy`, `finalize`, `project attach/detach`, and `toolchain slim` are invalid.
+The `lean-run` and `lean-runtime-catalog` executables are not installed.
+
+## Exit status
+
+- 0: successful operation or accepted proof
+- 1: completed negative result, such as a rejected proof or blocked plan
+- 2: invalid invocation, missing context, integrity, or infrastructure failure
+- 3–5: classified publication failures
+- 130: interrupted operation

{lean_runtime-3.0.3 → lean_runtime-4.0.1}/docs/development.md

@@ -33,7 +33,7 @@ python scripts/run_compatibility.py compatibility/mathlib-4.32.2.json
 The bundled discovery catalog is generated deterministically from exact locks:
 
 ```bash
-lean-runtime-catalog build catalog/environments.toml \
+lean-runtime catalog build catalog/environments.toml \
   --runtime-home .catalog-runtime \
   --output lean_runtime/discovery/data/catalog.json
 ```

lean_runtime-4.0.1/docs/environments.md

@@ -0,0 +1,32 @@
+# Exact environments
+
+Normal users let `check` infer environments. Infrastructure authors use `env`:
+
+```bash
+lean-runtime env lock environment.toml --output environment.lock.json
+lean-runtime env acquire environment.lock.json --name research-stack
+lean-runtime env list
+lean-runtime env info research-stack
+lean-runtime env diff old.lock.json environment.lock.json
+```
+
+`env lock` resolves tags to complete Git commits and trees and computes the
+canonical lock identity. `env acquire` makes that identity ready using verified
+local content, configured libraries, or exact source materialization. The
+mechanism does not change the semantic environment identity.
+
+Use `env acquire --download-only` to require a published artifact with no
+source fallback. Sparse environments can extend their verified import
+projection without changing identity; local/offline policy refuses missing
+closures before network access.
+
+Portable complete environments use:
+
+```bash
+lean-runtime env export research-stack --output stack.lean-environment
+lean-runtime env import stack.lean-environment --name imported-stack
+```
+
+Publication operators use `env publish` for one platform and `env finalize`
+after collecting the required platform descriptors. These are deliberately not
+top-level daily commands.

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.