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

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

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 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
+  lifecycles, so the toolchain transfer reports its real size instead of
+  inheriting a completed environment total.
+- Reject duplicate members and symlink extraction destinations in
+  slim-toolchain archives, matching the portable-environment boundary.
+- Correct the announcement gate's versioned plan-envelope parsing and add the
+  missing macOS Intel clean-consumer job.
+- Expand release acceptance coverage for archive limits and traversal,
+  deterministic multi-platform finalization, duplicate platforms, supported
+  Cosign releases, missing Cosign, and publisher identity/issuer mismatches.
+
 ## 3.0.2 - 2026-08-17
 
 - Route the first check directly through a newly downloaded slim Lean runtime.

lean_runtime-4.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: lean-runtime
+Version: 4.0.0
+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 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).

lean_runtime-4.0.0/README.md

@@ -0,0 +1,163 @@
+# 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 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).

lean_runtime-4.0.0/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.2 → lean_runtime-4.0.0}/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.0/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.0/docs/getting-started.md

@@ -0,0 +1,42 @@
+# Getting started
+
+Install the released wheel:
+
+```bash
+python -m pip install lean-runtime
+lean-runtime --version
+```
+
+For a new project:
+
+```bash
+lean-runtime new MyProof
+cd MyProof
+lean-runtime check
+```
+
+For an existing pinned Lake project:
+
+```bash
+cd ExistingProject
+lean-runtime check
+lean-runtime adopt
+```
+
+The initial check works before adoption. Adoption is the optional storage and
+reuse optimization: it verifies the current manifest and dependency checkouts,
+reuses their bytes, previews the transition, and rolls back if the attached
+graph does not probe successfully.
+
+For a standalone proof:
+
+```bash
+lean-runtime check Main.lean
+```
+
+Lean Runtime infers the context. Add strict source frontmatter or `--using`
+only when you need an exact override. A second check reuses the exact cached
+environment; `--offline` guarantees that no acquisition occurs.
+
+Run `lean-runtime status` to see what was selected and `lean-runtime doctor`
+when a prerequisite or store needs attention.

{lean_runtime-3.0.2 → lean_runtime-4.0.0}/docs/index.md

@@ -6,7 +6,7 @@ exact reusable environment, then returns structured results and a record of what
 was used.
 
 ```text
-lean-runtime run FILE / lean-run FILE / lean.setup(CONTEXT)
+lean-runtime check FILE / lean.setup(CONTEXT)
                 │
                 ├── pinned local project ───────────> ProjectEnvironment
                 └── dependencies / exact lock ─────> Environment
@@ -17,9 +17,9 @@ lean-runtime run FILE / lean-run FILE / lean.setup(CONTEXT)
                                                ExecutionResult + provenance
 ```
 
-- `lean-runtime run FILE` discovers or selects context for one file.
-- `lean-runtime check` operates in a known environment or pinned project.
-- `lean-run FILE` is a shortcut for `lean-runtime run FILE`.
+- `lean-runtime check FILE` discovers or selects context for one file.
+- `lean-runtime check` checks the current pinned Lake project.
+- `lean-runtime adopt` safely shares dependencies from existing projects.
 
 It deliberately does not replace the official tools:
 

lean_runtime-4.0.0/docs/local-projects.md

@@ -0,0 +1,70 @@
+# Local Lake projects
+
+Lean Runtime discovers the nearest pinned Lake project from the current
+directory or source path.
+
+```bash
+lean-runtime check
+lean-runtime check MyProject/Basic.lean
+lean-runtime build
+lean-runtime watch MyProject/Basic.lean
+```
+
+Focused checking passes the real project-relative path to Lake. Project-wide
+checking builds local libraries' Lean artifacts; `build` retains ordinary Lake
+build semantics and root outputs.
+
+## Create
+
+```bash
+lean-runtime new MyProof
+```
+
+`new` only creates projects. It chooses the stable cataloged Mathlib/toolchain,
+creates exact Lake metadata, shares exact dependency storage, and optionally
+generates CI. It refuses an existing Lake project; use `adopt` there.
+
+## Adopt an existing project
+
+```bash
+cd ExistingProject
+lean-runtime adopt
+```
+
+Adoption does not update the toolchain or manifest. It validates pinned Git
+dependencies, checks dirty/mismatched checkouts, uses the existing
+`.lake/packages` as an exact byte donor, prepares the shared graph, probes it,
+then atomically replaces package directories with links. The old graph is
+restored if any post-swap probe fails.
+
+For many repositories:
+
+```bash
+lean-runtime adopt ~/research
+```
+
+A directory that is itself a Lake project is adopted as one project; otherwise
+Lean Runtime discovers pinned projects below it. Independent failures do not
+prevent safe projects from being processed.
+
+Advanced equivalents are `project scan`, `project share`, and `project
+unshare`. They also default to the current directory.
+
+## Existing Elan
+
+If the exact pinned toolchain already exists in the user's Elan home, Lean
+Runtime invokes its `lean`/`lake` binaries read-only. It never changes the user
+default, installs there, or prunes it. Missing toolchains go to the private
+runtime store. `toolchain optimize` can create a verified slim checking copy;
+pruning is allowed only for a private original.
+
+## Update
+
+```bash
+lean-runtime update
+```
+
+The command shows the exact old/new Mathlib commit and toolchain, local reuse,
+and download requirements before confirmation. Application is transactional;
+project metadata is restored if the new graph or project-wide check fails.
+Use `--dry-run`, `--offline`, or `--yes` when scripting.