lean-runtime 0.6.0__tar.gz → 2.0.0__tar.gz

lean_runtime-2.0.0/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 2.0.0
+
+Version 2 gives the public interface the language used by Lean users rather
+than the language of its storage implementation. The environment format stays
+compatible; command names, Python names, configuration, events, and public
+metadata intentionally change without aliases.
+
+### Public terminology
+
+- Environment libraries replace OCI caches in ordinary configuration and docs.
+- Downloadable environments replace prebuilt artifacts.
+- Portable copies replace OCI bundles.
+- Publisher verification replaces signature-policy terminology.
+- Cleanup and storage replace garbage-collection and blob terminology.
+- Ready-to-run programs replace execution-capsule and container terminology.
+
+### Main migrations
+
+- `Runtime(caches=..., prebuilt=...)` becomes
+  `Runtime(libraries=..., availability=...)`.
+- `resolve`, `ensure`, and named `open` become `prepare`, `open_exact`, and
+  `environment` in the explicit Python API.
+- `export_environment` and `import_environment` become `save_portable_copy`
+  and `open_portable_copy`.
+- CLI workflows use `prepare`, `open`, `download`, `build-and-publish`,
+  `save-copy`, `open-copy`, `compare`, `storage`, and `clean`.
+- Environment libraries accept friendly `ghcr.io/owner/name` locations; the
+  OCI transport remains an advanced implementation detail.
+- Ready-to-run programs can be created, verified, copied, downloaded from a
+  program library, published for multiple kinds of computers, and interrupted
+  during interactive execution.
+
+## 1.0.0
+
+Lean Runtime v1 establishes the concise `lean-run` and `lean.setup()` workflows while making
+exact environments independently verifiable, explainable, measurable, and portable.
+
+### Breaking changes
+
+- Remove `lean-runtime audit`, `Runtime.audit()`, `AuditReport`, and `ArtifactInventory`;
+  `verify` is the sole trust surface and `verify --rebuild` performs independent rebuild checks.
+- Close and version the seven public CLI JSON schemas. Execution payloads now include stable
+  phase timings, while `inspect` and `gc` use one canonical data shape each.
+- Remove transitional compatibility surfaces introduced before v1; callers should use the
+  top-level façade, `Runtime`, and the documented v1 result types directly.
+
+### Release capabilities
+
+- Add lazy `setup`, `check`, `check_file`, and `replay` Python façade functions.
+- Add `lean-run` with strict TOML frontmatter, automatic local-project discovery,
+  exact lock input/output, concise progress, and structured JSON output.
+- Add exact `mathlib@REVISION`, `leancert@REVISION`, and
+  `owner/repository@REVISION` package references without permitting floating aliases.
+- Add `ExecutionResult.raise_for_error()` and structured `LeanCheckError` failures.
+- Rewrite the README around the front-facing workflow and expand the standalone
+  file, CLI, Python, and routing documentation.
+- Discover pinned local Lake projects from contained Lean files and expose a
+  distinct mutable `ProjectEnvironment` API.
+- Preserve project-relative file checks and record content, configuration,
+  manifest, and Git project provenance without claiming an environment identity.
+- Add transparent OCI prebuilt-cache lookup with authenticated registry pulls,
+  disk-backed blob reuse, strict fallback policy, and explicit `pull` support.
+- Add deterministic OCI publishing through `build-and-push`, with blobs and the
+  platform manifest committed before the lock-level index tag.
+- Stream bundle layers and OCI archives through temporary files instead of
+  materializing multi-gigabyte package layers in memory.
+- Add deterministic OCI image-layout export and verified, atomic environment import.
+- Verify bundle digests, lock and environment identities, package Git trees,
+  archive paths, host compatibility, and a Lean probe before publication.
+- Separate artifact compatibility identity from informational host metadata and
+  bump the environment store identity schema.
+- Add verification, decision explanations, semantic context diffs, repeated profiles, and
+  bounded matrix execution over ordinary execution results.
+- Add interruptible toolchain installation, Lake resolution, environment builds, matrix checks,
+  and project checks with process-group cleanup on cancellation and Ctrl-C.
+- Ship the public JSON schemas in wheel and source distributions and expose `schema_path()`.
+- Add reproducible case-study fixtures, clean-wheel smoke testing, and installed-wheel Lean
+  acceptance in CI.
+
+## 0.6.0
+
+- Discover packages declared with either `lakefile.toml` or `lakefile.lean`.
+- Translate Lake DSL configurations through the package's exact declared Lean
+  toolchain instead of parsing Lean source or guessing package metadata.
+
+## 0.5.0
+
+- Add `Environment.execute()` for generic commands such as `lake exe`.
+- Add managed `InteractiveSession` processes with live UTF-8 standard-I/O pipes.
+- Run interactive tools in disposable environment clones with exact provenance.
+- Enforce local timeout, memory, CPU, and bounded-transcript policies for sessions.
+- Gracefully close sessions with stdin EOF before process-group termination.
+- Persist final interactive `ExecutionResult` records and clean up instances.
+
+## 0.4.0
+
+- Add `github:owner/repository@tag-or-commit` package references.
+- Discover package identity, root module, and Lean toolchain from Lake projects.
+- Pin convenience references to exact commits before environment resolution.
+- Add one-shot `lean-runtime check FILE --with REFERENCE` execution.
+- Add `Runtime.spec_from_references()`, `resolve_references()`,
+  `ensure_references()`, and `Runtime.check(..., packages=[...])`.
+- Detect incompatible discovered toolchains across multi-package requests.
+- Avoid Elan's implicit toolchain installation during installation checks.
+
+## 0.3.0
+
+- Add safe multi-file checking and replayable multi-file captures.
+- Add cancellable native asyncio helpers.
+- Add structured lifecycle progress events.
+- Resolve friendly Git tags into exact commit locks.
+- Add installation health, cache status, environment listing, and richer inspection.
+- Add a scheduled real-ecosystem compatibility profile.
+- Store compact, content-verified one-commit source snapshots.
+- Treat direct and transitive package toolchain files as compatibility signals,
+  while making the actual selected-toolchain build authoritative.
+- Use execution leases so batch checks can clone concurrently without racing GC.
+- Build imported locked-package roots on demand inside execution workspaces.
+- Add release automation for PyPI trusted publishing.
+- Build and deploy the documentation site through GitHub Pages.
+
+## 0.2.0
+
+- Introduce content-addressed environments, exact Git locks, offline reopening,
+  execution provenance, captures, aliases, garbage collection, and trusted local
+  resource policies.

{lean_runtime-0.6.0 → lean_runtime-2.0.0}/MANIFEST.in

@@ -4,4 +4,5 @@ recursive-include docs *.md
 recursive-include examples *.toml
 recursive-include compatibility *.json *.md *.toml
 recursive-include scripts *.py
+recursive-include schemas *.json
 recursive-include tests *.py

lean_runtime-2.0.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: lean-runtime
+Version: 2.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"
+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
+
+Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
+Lake project or rebuilding the same dependencies on every machine.
+
+Lean Runtime discovers the exact Lean environment a project needs and reuses a
+downloadable copy when one is available. It returns structured Lean results
+with a record of the toolchain and dependencies that were actually used.
+
+> **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
+> it is an orchestration boundary, not a security sandbox.
+
+## Install
+
+```bash
+python -m pip install lean-runtime
+```
+
+Lean Runtime manages its own Elan installation on macOS and Linux. Windows
+currently requires `LEAN_RUNTIME_ELAN`.
+
+## Run one Lean file
+
+Inside an existing pinned Lake project, just pass the file:
+
+```bash
+lean-run MyProject/Main.lean
+```
+
+For a portable standalone file, declare exact dependencies in TOML frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.32.2"]
+-- ///
+
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```bash
+lean-run Main.lean
+```
+
+The same context can be supplied from the command line:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2
+```
+
+Create an exact lock for CI without changing the file:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2 \
+  --lock-out environment.lock.json
+lean-run Main.lean --lock environment.lock.json
+```
+
+## Python
+
+Configure an environment once, then use it repeatedly:
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(["mathlib@v4.32.2"])
+
+result = env.check(
+    """
+    import Mathlib
+    example : 2 + 2 = 4 := by norm_num
+    """
+)
+result.raise_for_error()
+```
+
+Batch and asyncio APIs reuse that prepared environment:
+
+```python
+results = env.check_many(generated_proofs, concurrency=8)
+results = await env.check_many_async(generated_proofs, concurrency=20)
+```
+
+Local projects use the same setup pattern while retaining mutable-project
+semantics:
+
+```python
+project = lean.setup(project="./my-project")
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+One-shot helpers are available when setup reuse is unnecessary:
+
+```python
+result = lean.check(source, deps=["mathlib@v4.32.2"])
+result = lean.check_file("./my-project/MyProject/Main.lean")
+```
+
+When you need evidence rather than extra setup, the operations CLI can verify, explain,
+compare, and measure the same exact contexts:
+
+```bash
+lean-runtime verify research-stack --offline
+lean-runtime compare previous.lock.json environment.lock.json
+lean-runtime profile research-stack Main.lean --repeat 5
+lean-runtime matrix compatibility.toml Main.lean
+```
+
+Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and
+`--timings` to expose preparation versus execution time. Successful ordinary checks remain
+one concise line.
+
+Friendly references remain exact: use `mathlib@VERSION`,
+`leancert@VERSION`, `owner/repository@REVISION`, or the explicit
+`github:owner/repository@REVISION` form. Bare floating package names are never
+accepted.
+
+## Share environments
+
+A **project** is your ordinary Lake repository. Its **environment** is the exact
+Lean version, dependencies, and build configuration needed to use it. A
+**downloadable environment** is a ready-to-use copy that collaborators and CI
+can fetch instead of rebuilding Mathlib.
+
+Environment libraries may be public or private. For example:
+
+```bash
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/owner/lean-environments
+```
+
+For an already-built executable, Lean Runtime can also create a verified
+**ready-to-run program**. It opens without rebuilding the project, can be saved
+as a portable copy, and can be shared through a public or private program
+library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md).
+
+## Technical details
+
+The simple API is backed by exact Git commits and trees, Lake-resolved locks,
+platform-aware content-addressed environments, atomic cross-process builds,
+downloadable environment reuse, replayable provenance, verification, and trusted
+publishers. The libraries use OCI-compatible storage internally, but users do
+not need Docker or container concepts. Advanced protocol details remain in the
+architecture documentation.
+
+## Documentation
+
+- [Getting started](https://github.com/alerad/lean-runtime/blob/main/docs/getting-started.md)
+- [Python API](https://github.com/alerad/lean-runtime/blob/main/docs/python-api.md)
+- [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
+- [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
+- [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
+- [Portable copies and environment libraries](https://github.com/alerad/lean-runtime/blob/main/docs/portable-copies.md)
+- [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md)
+- [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
+- [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
+- [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)
+
+## License
+
+Apache License 2.0.

lean_runtime-2.0.0/README.md

@@ -0,0 +1,163 @@
+# Lean Runtime
+
+Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
+Lake project or rebuilding the same dependencies on every machine.
+
+Lean Runtime discovers the exact Lean environment a project needs and reuses a
+downloadable copy when one is available. It returns structured Lean results
+with a record of the toolchain and dependencies that were actually used.
+
+> **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
+> it is an orchestration boundary, not a security sandbox.
+
+## Install
+
+```bash
+python -m pip install lean-runtime
+```
+
+Lean Runtime manages its own Elan installation on macOS and Linux. Windows
+currently requires `LEAN_RUNTIME_ELAN`.
+
+## Run one Lean file
+
+Inside an existing pinned Lake project, just pass the file:
+
+```bash
+lean-run MyProject/Main.lean
+```
+
+For a portable standalone file, declare exact dependencies in TOML frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.32.2"]
+-- ///
+
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```bash
+lean-run Main.lean
+```
+
+The same context can be supplied from the command line:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2
+```
+
+Create an exact lock for CI without changing the file:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2 \
+  --lock-out environment.lock.json
+lean-run Main.lean --lock environment.lock.json
+```
+
+## Python
+
+Configure an environment once, then use it repeatedly:
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(["mathlib@v4.32.2"])
+
+result = env.check(
+    """
+    import Mathlib
+    example : 2 + 2 = 4 := by norm_num
+    """
+)
+result.raise_for_error()
+```
+
+Batch and asyncio APIs reuse that prepared environment:
+
+```python
+results = env.check_many(generated_proofs, concurrency=8)
+results = await env.check_many_async(generated_proofs, concurrency=20)
+```
+
+Local projects use the same setup pattern while retaining mutable-project
+semantics:
+
+```python
+project = lean.setup(project="./my-project")
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+One-shot helpers are available when setup reuse is unnecessary:
+
+```python
+result = lean.check(source, deps=["mathlib@v4.32.2"])
+result = lean.check_file("./my-project/MyProject/Main.lean")
+```
+
+When you need evidence rather than extra setup, the operations CLI can verify, explain,
+compare, and measure the same exact contexts:
+
+```bash
+lean-runtime verify research-stack --offline
+lean-runtime compare previous.lock.json environment.lock.json
+lean-runtime profile research-stack Main.lean --repeat 5
+lean-runtime matrix compatibility.toml Main.lean
+```
+
+Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and
+`--timings` to expose preparation versus execution time. Successful ordinary checks remain
+one concise line.
+
+Friendly references remain exact: use `mathlib@VERSION`,
+`leancert@VERSION`, `owner/repository@REVISION`, or the explicit
+`github:owner/repository@REVISION` form. Bare floating package names are never
+accepted.
+
+## Share environments
+
+A **project** is your ordinary Lake repository. Its **environment** is the exact
+Lean version, dependencies, and build configuration needed to use it. A
+**downloadable environment** is a ready-to-use copy that collaborators and CI
+can fetch instead of rebuilding Mathlib.
+
+Environment libraries may be public or private. For example:
+
+```bash
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/owner/lean-environments
+```
+
+For an already-built executable, Lean Runtime can also create a verified
+**ready-to-run program**. It opens without rebuilding the project, can be saved
+as a portable copy, and can be shared through a public or private program
+library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md).
+
+## Technical details
+
+The simple API is backed by exact Git commits and trees, Lake-resolved locks,
+platform-aware content-addressed environments, atomic cross-process builds,
+downloadable environment reuse, replayable provenance, verification, and trusted
+publishers. The libraries use OCI-compatible storage internally, but users do
+not need Docker or container concepts. Advanced protocol details remain in the
+architecture documentation.
+
+## Documentation
+
+- [Getting started](https://github.com/alerad/lean-runtime/blob/main/docs/getting-started.md)
+- [Python API](https://github.com/alerad/lean-runtime/blob/main/docs/python-api.md)
+- [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
+- [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
+- [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
+- [Portable copies and environment libraries](https://github.com/alerad/lean-runtime/blob/main/docs/portable-copies.md)
+- [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md)
+- [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
+- [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
+- [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)
+
+## License
+
+Apache License 2.0.

{lean_runtime-0.6.0 → lean_runtime-2.0.0}/docs/architecture.md

@@ -1,5 +1,16 @@
 # Architecture
 
+## Ready-to-run programs
+
+A ready-to-run program is the small result you can open immediately, without
+rebuilding its Lean project first. Lean Runtime verifies its files every time it
+is opened and records the exact source revision and, when known, the environment
+that produced it. Use one for fast service execution. Open the full environment
+when you need kernel replay, custom compilation, or an independent rebuild.
+
+Program libraries and portable program copies use OCI-compatible storage under
+the hood. That transport detail does not appear in the ordinary Python API or CLI.
+
 ## Dominant abstraction
 
 Lean Runtime is an environment compiler:

lean_runtime-2.0.0/docs/case-study-v1.md

@@ -0,0 +1,47 @@
+# V1 release case study
+
+The release case study demonstrates the public lifecycle rather than relying on private
+benchmark hooks. It uses a prepared exact Mathlib environment and the committed mixture of
+accepted proofs, elaboration failures, and malformed input.
+
+## Run the evidence harness
+
+```bash
+python scripts/run_v1_case_study.py research-stack \
+  --concurrency 1 --concurrency 4 --concurrency 8 --concurrency 20 \
+  --repeat 5 --output benchmarks/proof_batch/results.json
+```
+
+The resulting JSON records:
+
+- runtime, Python, platform, command, and fixture identity;
+- cache state before and after the workload;
+- raw wall-time samples and min/median/mean/p95/max by concurrency;
+- stable request identity and unique execution identity;
+- bundle size and export/import durations;
+- import into an empty runtime home;
+- offline verification and captured-execution replay.
+
+The harness deliberately starts from an already prepared environment. Measure cold source
+preparation separately and state whether local, Lake, and OCI libraries were empty. Do not combine
+cold source builds and warm execution into one headline number.
+
+## Clean-wheel acceptance
+
+Build and exercise the artifact users actually install:
+
+```bash
+python -m build
+python scripts/smoke_wheel.py dist/lean_runtime-1.0.0-py3-none-any.whl
+```
+
+Add `--lean` to bootstrap an isolated runtime home and run a real standalone proof. The smoke
+script creates a fresh virtual environment, installs only the wheel, clears ambient Python
+package visibility, checks both console entry points, and reads a packaged v1 schema through
+`lean_runtime.schema_path()`.
+
+## Publishing results
+
+Keep the raw JSON beside any summary. Record the exact lock and environment ID, machine and
+filesystem, command line, runtime version, repetition count, and cache state. Timings from noisy
+shared CI are evidence that the workflow completes, not a performance regression gate.

lean_runtime-2.0.0/docs/cli.md

@@ -0,0 +1,122 @@
+# Command-line interface
+
+## `lean-run`
+
+The front-facing command checks one file and discovers its context:
+
+```bash
+lean-run Main.lean
+lean-run Main.lean --with mathlib@v4.32.2
+lean-run Main.lean --lock environment.lock.json
+lean-run Main.lean --json
+lean-run Main.lean --explain
+lean-run Main.lean --timings
+```
+
+Use `--lock-out environment.lock.json` with dependencies to retain the exact
+resolved graph. See [Standalone Lean files](standalone-files.md) for frontmatter,
+routing precedence, conflict rules, and output behavior.
+
+## `lean-runtime`
+
+All commands accept `--home PATH` before the subcommand to select a store.
+
+## One-shot package workflow
+
+```bash
+lean-runtime check Main.lean \
+  --with github:alerad/leancert@v4.32.2.4
+```
+
+`--with` is repeatable. References use
+`mathlib@REVISION`, `OWNER/REPOSITORY@REVISION`, or the explicit
+`github:OWNER/REPOSITORY@REVISION` form. Package discovery reads the root
+`lean-toolchain` and `lakefile.toml`, pins the reference to a full commit, and
+then uses the normal lock and environment pipeline. Multiple discovered
+packages must declare the same toolchain unless `--toolchain` explicitly
+selects the compatibility build.
+
+Supporting files work here too:
+
+```bash
+lean-runtime check Main.lean \
+  --with github:alerad/leancert@v4.32.2.4 \
+  --include Support/Defs.lean
+```
+
+## Environment workflow
+
+```bash
+lean-runtime prepare environment.toml --output environment.lock.json
+lean-runtime open environment.lock.json --name research-stack
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime save-copy research-stack --output research-stack.lean-environment
+lean-runtime --home /tmp/fresh open-copy research-stack.lean-environment --name research-stack
+lean-runtime build-and-publish environment.lock.json --publish-to ghcr.io/owner/lean-environments
+lean-runtime check research-stack Main.lean --json
+lean-runtime inspect research-stack --packages
+lean-runtime environments
+lean-runtime storage
+lean-runtime doctor
+lean-runtime verify research-stack --offline
+lean-runtime compare old.lock.json new.lock.json
+lean-runtime profile research-stack Main.lean --repeat 5
+lean-runtime matrix matrix.toml Main.lean
+lean-runtime clean
+lean-runtime clean --execute
+```
+
+`clean` is a dry run unless `--execute` is supplied.
+
+`save-copy` creates a portable environment file. `open-copy` verifies its exact
+identity, package Git trees, computer compatibility, and Lean probe before
+making the environment available. See [Portable copies and environment
+libraries](portable-copies.md) for its trust boundary.
+
+## Replay
+
+```bash
+lean-runtime replay result.execution.json --json
+```
+
+Replay ensures the captured lock, reacquires missing exact sources if network
+is available, and then runs the captured request. An already published
+environment can replay offline.
+
+## Existing projects and core Lean
+
+```bash
+lean-runtime check-file Main.lean --toolchain 4.32.2
+lean-runtime check-file ./existing-project/MyProject/Main.lean
+lean-runtime build ./existing-project MyLibrary
+lean-runtime install 4.32.2
+```
+
+Without `--with`, the environment-aware `check` command requires an environment
+identifier. `check-file` is the direct local-project route. When no
+`--project` or `--toolchain` is supplied, it discovers the nearest directory
+containing a Lake configuration and `lean-toolchain`, then passes the actual
+project-relative file to `lake env lean`.
+
+Add supporting source files with repeatable `--include` options:
+
+```bash
+lean-runtime check research-stack Main.lean --include Support/Defs.lean
+```
+
+Resolution and materialization print structured lifecycle progress to stderr.
+Pass global `--quiet` before the subcommand to suppress it.
+
+Pass global `--timings` before the subcommand for stable phase timing output. Machine-readable
+execution output uses the versioned `lean-runtime.execution/v1` envelope; the other v1
+schemas and advanced command examples are documented in
+[Verify, understand, compare, and measure](v1-precision.md).
+
+Global `--library` is repeatable and `--availability auto|required|local`
+controls whether ready-to-use environments are downloaded or built locally.
+`LEAN_RUNTIME_LIBRARIES` accepts a comma-separated equivalent and
+`LEAN_RUNTIME_AVAILABILITY` sets the default policy.
+
+Use global `--publisher_verification required --trusted-publisher ID --trusted-issuer ISSUER`
+to require a verified publisher. `build-and-publish --sign` records the trusted
+publisher using the configured Cosign identity.