lean-runtime 4.24.0__tar.gz → 4.26.0__tar.gz

{lean_runtime-4.24.0 → lean_runtime-4.26.0}/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## Unreleased
 
+## 4.26.0 - 2026-08-26
+
+- Stop `status` claiming a download is required for core-only files. A lock
+  without packages runs straight on the toolchain and never materializes an
+  environment in the store, so readiness and cost are now judged by the
+  toolchain alone: `status` reports `environment ready locally` and
+  `Download none` once the toolchain is installed, and `status --probe`
+  prices it as zero instead of `unknown`. Previously the store directory that
+  `check` never creates kept the row at `not local · Download required`.
+
+## 4.25.0 - 2026-08-26
+
+- Pin the Elan build that automatic bootstrap installs. Bootstrap now
+  downloads the `v4.2.3` release archive for the host platform directly from
+  the Elan releases, verifies its SHA-256, and runs its `elan-init`, instead of
+  running the installer script that always fetched `releases/latest`. Two
+  machines on the same Lean Runtime version therefore get the same Elan.
+- Retry `elan toolchain install` up to two more times when Elan reports a
+  transient download failure (dropped connection, TLS handshake error,
+  timeout), announcing each retry as a `toolchain.install_retry` event. Unknown
+  toolchains and disk errors still fail immediately.
+- State the model up front: `lean-runtime --help`, the docs index, and the
+  command reference now open with the four nouns (context, environment, lock,
+  verdict) and the rule that discovery proposes an environment while only Lean
+  accepts it.
+- Make `status` a dry run of `check`. A standalone file reports its context
+  source and confidence (`proposed` for discovery, `exact` for a project, lock,
+  or stored environment), the candidates in the order `check` would try them,
+  whether each environment and toolchain is already local, and whether a
+  download is needed; `status --probe` prices the first download.
+- Report Lean's answer as a first-class `verdict` (`accepted`, `rejected`, or
+  `not_run`) in execution results, `--json` output (`data.verdict`), and the
+  `--matrix` table, and attribute every human-readable verdict to the exact
+  environment it was produced in.
+- Wrap `status --json` in a `lean-runtime.status/v1` envelope like every other
+  machine-readable command. Scripts that read the bare object must now read
+  `data`.
+- Apply one mutation rule everywhere: `toolchain optimize --prune-original`,
+  `env publish`, `toolchain publish`, `program publish`, and
+  `declaration-index publish` now describe the change and require `--yes` or an
+  interactive confirmation, exiting with code `2` non-interactively otherwise.
+- Separate the vocabulary of *context* (where the decision comes from) and
+  *environment* (what was chosen) across help text and documentation;
+  `check --help` and `status --help` now describe the model, `--using` takes
+  an `ENVIRONMENT`, and the generated `AGENTS.md` opens with the same model
+  plus the `status` dry run and the `--yes` rule.
+- Improve Windows checks by reusing Elan from `PATH`, recognizing native
+  `.exe` toolchain binaries, and running core-only discovery directly against
+  its exact Lean toolchain when no platform environment artifact is needed.
+- Treat files outside every declared `lakefile.toml` target as standalone even
+  when they sit below a pinned project, add `check --standalone` as an explicit
+  override, and explain ignored parent projects in `status`.
+
 ## 4.24.0 - 2026-08-26
 
 - Key shared Lake package artifacts by the exact installed Lean and Lake

{lean_runtime-4.24.0/lean_runtime.egg-info → lean_runtime-4.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 4.24.0
+Version: 4.26.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -63,6 +63,23 @@ reuse.
 [Read the documentation](https://alerad.github.io/lean-runtime/) ·
 [Explore the CLI](https://alerad.github.io/lean-runtime/reference/commands/)
 
+## The model
+
+| Noun | Meaning |
+| --- | --- |
+| **context** | where a file's requirements come from: `--using`, frontmatter, the owning Lake project, or automatic discovery |
+| **environment** | one exact, immutable toolchain + package set |
+| **lock** | an environment written down, reusable offline anywhere |
+| **verdict** | Lean's answer inside one environment: `accepted` or `rejected` |
+
+Discovery proposes an environment. Only Lean accepts it. `lean-runtime status`
+shows the proposal without running anything; `lean-runtime check` produces the
+verdict and names the environment it was produced in:
+
+```text
+✓ Main.lean accepted in mathlib-v4.33.0 (3.21s)
+```
+
 ## Start where you are
 
 Create a project:
@@ -107,7 +124,7 @@ Record the environment only when the result must be reproduced elsewhere:
 lean-runtime check Main.lean --write-lock environment.lock.json
 ```
 
-A file can instead carry an explicit context in strict comment frontmatter:
+A file can instead name its environment in strict comment frontmatter:
 
 ```lean
 -- /// lean-runtime
@@ -118,7 +135,7 @@ import Mathlib
 example : 2 + 2 = 4 := by norm_num
 ```
 
-When inference needs an override, there is one spelling:
+When discovery needs an override, there is one spelling:
 
 ```bash
 lean-runtime check Main.lean --using mathlib@v4.33.0
@@ -145,7 +162,7 @@ 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
+status [PATH]    dry run of check: where the environment comes from, what it costs
 verify SUBJECT   verify an exact artifact
 doctor           diagnose and offer safe repairs
 clean            preview and reclaim unused storage
@@ -153,9 +170,10 @@ replay CAPTURE   replay an execution capture
 completion SHELL generate shell completion
 ```
 
-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`.
+Project commands use the current directory when no path is supplied. Every
+command that changes a project, deletes local content, or publishes to a remote
+shows its plan and asks 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
@@ -223,8 +241,9 @@ interfaces for infrastructure code.
 - 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.
+- A Lean rejection is a normal verdict and exits 1. Invalid or infrastructure
+  invocations exit 2 and carry no verdict. 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.24.0 → lean_runtime-4.26.0}/README.md

@@ -27,6 +27,23 @@ reuse.
 [Read the documentation](https://alerad.github.io/lean-runtime/) ·
 [Explore the CLI](https://alerad.github.io/lean-runtime/reference/commands/)
 
+## The model
+
+| Noun | Meaning |
+| --- | --- |
+| **context** | where a file's requirements come from: `--using`, frontmatter, the owning Lake project, or automatic discovery |
+| **environment** | one exact, immutable toolchain + package set |
+| **lock** | an environment written down, reusable offline anywhere |
+| **verdict** | Lean's answer inside one environment: `accepted` or `rejected` |
+
+Discovery proposes an environment. Only Lean accepts it. `lean-runtime status`
+shows the proposal without running anything; `lean-runtime check` produces the
+verdict and names the environment it was produced in:
+
+```text
+✓ Main.lean accepted in mathlib-v4.33.0 (3.21s)
+```
+
 ## Start where you are
 
 Create a project:
@@ -71,7 +88,7 @@ Record the environment only when the result must be reproduced elsewhere:
 lean-runtime check Main.lean --write-lock environment.lock.json
 ```
 
-A file can instead carry an explicit context in strict comment frontmatter:
+A file can instead name its environment in strict comment frontmatter:
 
 ```lean
 -- /// lean-runtime
@@ -82,7 +99,7 @@ import Mathlib
 example : 2 + 2 = 4 := by norm_num
 ```
 
-When inference needs an override, there is one spelling:
+When discovery needs an override, there is one spelling:
 
 ```bash
 lean-runtime check Main.lean --using mathlib@v4.33.0
@@ -109,7 +126,7 @@ 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
+status [PATH]    dry run of check: where the environment comes from, what it costs
 verify SUBJECT   verify an exact artifact
 doctor           diagnose and offer safe repairs
 clean            preview and reclaim unused storage
@@ -117,9 +134,10 @@ replay CAPTURE   replay an execution capture
 completion SHELL generate shell completion
 ```
 
-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`.
+Project commands use the current directory when no path is supplied. Every
+command that changes a project, deletes local content, or publishes to a remote
+shows its plan and asks 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
@@ -187,8 +205,9 @@ interfaces for infrastructure code.
 - 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.
+- A Lean rejection is a normal verdict and exits 1. Invalid or infrastructure
+  invocations exit 2 and carry no verdict. 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.26.0/docs/concepts/context-selection.md

@@ -0,0 +1,89 @@
+# Context selection
+
+Every check runs inside one exact **environment**. The **context** is where that
+environment comes from. Selecting a context and Lean accepting the source are
+separate decisions: discovery proposes an environment, and only Lean accepts it.
+
+For ordinary standalone checks, let Lean Runtime discover the environment.
+Explicit selection 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:
+
+1. An explicit command-line or Python API selection
+2. Lean Runtime frontmatter in the file
+3. The nearest pinned Lake project that owns the file
+4. Automatic catalog discovery
+
+If none can produce an environment, the operation fails before Lean runs.
+
+The first three sources are **exact**: they name one environment outright. The
+fourth is only a **proposal** until Lean accepts the file inside a candidate.
+`status` reports which of the two it is.
+
+## Explicit selection
+
+```console
+lean-runtime check Main.lean --using mathlib@v4.33.0
+```
+
+`--using` can identify a project directory, a lock file, a stored environment, a
+toolchain, or a package release. Explicit input does not need discovery.
+
+## Frontmatter
+
+```lean
+-- /// lean-runtime
+-- toolchain = "leanprover/lean4:v4.33.0"
+-- ///
+example : 1 + 1 = 2 := by decide
+```
+
+Frontmatter travels with the source while remaining valid Lean comments.
+
+## Pinned project context
+
+A file declared beneath a target in a `lakefile.toml` project uses the nearest
+project with a pinned toolchain. A file that is merely stored under that project,
+but outside every declared target root, proceeds to automatic discovery. For an
+imperative `lakefile.lean`, where ownership cannot be established without running
+project code, Lean Runtime conservatively preserves ancestry-based selection.
+Lean Runtime does not replace project version decisions during a normal project check.
+
+To explicitly ignore every ancestor project, use:
+
+```console
+lean-runtime check Main.lean --standalone
+```
+
+`--standalone` cannot be combined with `--using` because they are competing
+context-selection instructions.
+
+## Automatic discovery
+
+Discovery begins with declared source imports. The bundled catalog associates exact environments with module inventories. Plausible candidates are ordered under a bounded policy and checked in turn.
+
+Static analysis proposes candidates. It does not prove compatibility. A candidate is accepted only if Lean accepts the source inside that exact environment.
+
+Candidate count, compiler time, wall time, remote acquisition, offline mode, and source-build permission can bound the search. Reaching a bound can produce an inconclusive discovery result rather than a claim that no compatible environment exists.
+
+## Inspect the decision
+
+```console
+lean-runtime status Main.lean
+lean-runtime status Main.lean --probe
+lean-runtime status Main.lean --json
+```
+
+`status` is a dry run of `check`. For a standalone file it reports the context
+source, its confidence (`proposed` for discovery, `exact` for a project, lock, or
+stored environment), the imports used as evidence, the candidate environments in
+the order `check` would try them, whether each environment and toolchain is
+already local, and — with `--probe` — the size of the first download. It also
+names an ancestor project that was ignored because no declared target owns the
+file. `status` never runs Lean and never acquires anything.
+
+A successful `check` reports the verdict together with the environment that
+produced it, and its `--json` provenance records the exact identities involved.

{lean_runtime-4.24.0 → lean_runtime-4.26.0}/docs/index.md

@@ -24,7 +24,7 @@ hide:
   <div class="lr-hero-copy">
     <p class="lr-eyebrow"><span aria-hidden="true">⊢</span> Compiler-backed Lean execution</p>
     <h1>Check a Lean file in the environment it needs.</h1>
-    <p class="lr-lead">Lean Runtime resolves an exact toolchain and dependency context, runs Lean, and records what actually ran.</p>
+    <p class="lr-lead">Lean Runtime resolves one exact environment — toolchain and dependencies — runs Lean inside it, and records what actually ran.</p>
     <div class="lr-actions">
       <a class="md-button md-button--primary" href="tutorial/">Run your first check</a>
       <a class="md-button" href="concepts/context-selection/">How context is selected</a>
@@ -83,6 +83,36 @@ hide:
 
 
 
+<section class="lr-workflows" aria-labelledby="model-title">
+  <div class="lr-section-heading">
+    <p class="lr-kicker">The model</p>
+    <h2 id="model-title">Four nouns and one rule.</h2>
+  </div>
+  <div class="lr-card-grid">
+    <article>
+      <p class="lr-card-label">Context</p>
+      <h3>Where requirements come from</h3>
+      <p><code>--using</code>, frontmatter, the owning Lake project, or automatic discovery — in that order.</p>
+    </article>
+    <article>
+      <p class="lr-card-label">Environment</p>
+      <h3>One exact, immutable set</h3>
+      <p>A toolchain plus every package at a pinned revision. Identified by content, never by a mutable tag.</p>
+    </article>
+    <article>
+      <p class="lr-card-label">Lock</p>
+      <h3>An environment written down</h3>
+      <p>Reusable on any machine, including with network access disabled.</p>
+    </article>
+    <article>
+      <p class="lr-card-label">Verdict</p>
+      <h3>Lean's answer</h3>
+      <p><code>accepted</code> or <code>rejected</code>, always inside one named environment. A rejection is a normal result.</p>
+    </article>
+  </div>
+  <p class="lr-lead"><strong>Discovery proposes an environment. Only Lean accepts it.</strong> <code>status</code> shows the proposal; <code>check</code> produces the verdict.</p>
+</section>
+
 <section class="lr-workflows" aria-labelledby="workflows-title">
   <div class="lr-section-heading">
     <p class="lr-kicker">Workflows</p>

lean_runtime-4.26.0/docs/reference/commands.md

@@ -0,0 +1,110 @@
+# Commands
+
+This page summarizes the command surface. Run `lean-runtime COMMAND --help` for the installed version's complete arguments and options.
+
+## The model
+
+| Noun | Meaning |
+| --- | --- |
+| context | Where a file's requirements come from: `--using`, frontmatter, the owning Lake project, or automatic discovery. |
+| environment | One exact, immutable toolchain + package set. |
+| lock | An environment written down, reusable offline anywhere. |
+| verdict | Lean's answer inside one environment: `accepted` or `rejected`. |
+
+Discovery proposes an environment. Only Lean accepts it. `status` shows the
+proposal; `check` produces the verdict.
+
+## Daily workflows
+
+| Command | Purpose |
+| --- | --- |
+| `new NAME` | Create a Lean project. |
+| `adopt [PATH]` | Register existing Lake projects and prepare shared dependency storage. |
+| `check [PATH ...]` | Check a project or Lean source with a discovered or explicit environment. |
+| `watch FILE` | Recheck one project file when it changes. |
+| `build [TARGET ...]` | Build the current Lake project. |
+| `update [PATH]` | Apply the latest cataloged Mathlib/toolchain update; non-Mathlib projects are a no-op. |
+| `publish [PATH]` | Configure project publication. |
+
+## Inspection and maintenance
+
+| Command | Purpose |
+| --- | --- |
+| `status [SUBJECT]` | Dry run of `check`: the context source, its confidence, the environments discovery would try, and whether a download is needed. `--probe` prices the first download. |
+| `verify SUBJECT` | Verify a lock, environment, or artifact. |
+| `doctor` | Diagnose the local installation and configuration. |
+| `clean` | Preview and reclaim unused runtime storage. |
+| `replay CAPTURE` | Replay an execution capture. |
+| `completion SHELL` | Generate shell completion. |
+
+## Advanced namespaces
+
+| Namespace | Scope |
+| --- | --- |
+| `env` | Exact immutable environments and locks. |
+| `project` | Mutable project inspection, sharing, locks, and exports. |
+| `toolchain` | Toolchain installation, inspection, optimization, and publication. |
+| `storage` | Storage usage and verification; see [Storage](storage.md). |
+| `program` | Ready-to-run program artifacts. |
+| `catalog` | Discovery catalog maintenance. |
+
+## Common check options
+
+```console
+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 environment.
+
+Automatic discovery is the normal standalone workflow. `--using` selects the
+environment explicitly when a package release, lock, toolchain, stored
+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.
+
+## Commands that change things
+
+Commands that change a project, delete local content, or push to a remote
+describe the change first and apply it only with `--yes` or an interactive
+confirmation. Most also accept `--dry-run`. Non-interactive runs without
+`--yes` exit with code `2` and change nothing. See
+[Trust](../trust.md#which-commands-change-what) for the full list.
+
+## Machine output
+
+Every command that accepts `--json` writes exactly one JSON envelope to
+standard output — never an empty stream — and exits non-zero on failure:
+
+```json
+{"schema": "lean-runtime.execution/v1", "ok": true, "data": {...}, "warnings": [], "errors": []}
+```
+
+Schemas ship with the package (`lean_runtime.schema_path(NAME)`):
+`execution`, `check-batch`, `matrix`, `profile`, `plan`, `status`, `verify`,
+`comparison`, `inspect`, `cleanup`, `publication`, and `attestation`, each
+suffixed `-v1.schema.json`. An execution result carries `data.verdict`
+(`accepted`, `rejected`, or `not_run`) in addition to `data.ok`.
+
+## Build cache control
+
+```console
+lean-runtime build
+lean-runtime build --no-cache
+```
+
+The default build may restore supported dependency artifacts before invoking Lake. `--no-cache` skips that restoration step.
+
+## Exit codes for check
+
+| Code | Verdict | Meaning |
+| --- | --- | --- |
+| `0` | `accepted` | Lean accepted the source. |
+| `1` | `rejected` | Lean ran and rejected the source. |
+| `2` | none | Invocation, context, acquisition, or configuration failed, or a resource limit such as `--timeout` was hit. |
+| `130` | none | Interrupted. |

{lean_runtime-4.24.0 → lean_runtime-4.26.0}/docs/reference/python-api.md

@@ -53,6 +53,11 @@ result = lean.check_file("./my-project/MyProject/Basic.lean")
 
 ## Read the result
 
+`result.verdict` is Lean's answer inside the environment that ran: `accepted`,
+`rejected`, or `not_run` when a timeout or cancellation cut the run short and
+no verdict exists. `result.ok` is true only for `accepted`. A rejection is a
+normal result, not an exception.
+
 Failed checks expose parsed diagnostics directly:
 
 ```python

{lean_runtime-4.24.0 → lean_runtime-4.26.0}/docs/trust.md

@@ -5,11 +5,15 @@ Lean Runtime records exact identities, verifies retained content, and reports th
 ## What it establishes
 
 - Exact package revisions and Git tree identities in environment locks
-- Toolchain identity
+- Toolchain identity, and the Elan build that automatic bootstrap installs
+  (pinned version, SHA-256 verified)
 - Content digests for retained and transferred artifacts
 - Platform compatibility metadata
-- Execution provenance for completed checks
-- Compiler acceptance or rejection for the source that ran
+- Execution provenance for completed checks, including `source_digest`, the
+  digest of the bytes Lean actually checked, and the environment and lock
+  identities it ran in
+- Compiler acceptance or rejection for the source that ran, reported as a
+  `verdict` attributed to one exact environment
 
 ## What it does not establish
 
@@ -19,9 +23,29 @@ Lean Runtime records exact identities, verifies retained content, and reports th
 - That a Lake build script is safe to execute
 - That package code cannot access the host system
 - That integrity verification provides process isolation
+- That a discovery proposal is compatible before Lean has accepted the file in it
 
 Lake packages and build scripts can execute code during acquisition or compilation. Treat unfamiliar dependencies as code you are about to run on your machine.
 
+## Which commands change what
+
+`check`, `status`, `verify`, `doctor`, and the inspection commands read your
+project and may add toolchains, environments, and caches under the runtime home
+(`LEAN_RUNTIME_HOME`). They never modify your project directory.
+
+Commands that change a project, delete local content, or push to a remote follow
+one rule: they describe the change first and apply it only with `--yes` or an
+interactive confirmation.
+
+| Command | Changes |
+| --- | --- |
+| `new`, `adopt`, `update`, `publish`, `project share`, `project unshare` | Your project directory |
+| `clean`, `doctor` repairs, `toolchain optimize --prune-original` | Local content under the runtime home |
+| `env publish`, `toolchain publish`, `program publish`, `declaration-index publish` | A remote library |
+
+In a non-interactive session these commands exit with code `2` unless `--yes`
+is given, so a script can never mutate or publish by accident.
+
 ## Verify retained content
 
 ```console