lean-runtime 2.9.2__tar.gz → 3.0.0__tar.gz

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/CHANGELOG.md

@@ -2,6 +2,121 @@
 
 ## Unreleased
 
+## 3.0.0 - 2026-08-16
+
+The first release with one canonical command vocabulary, capsule-only
+environment libraries, and documentation that states guarantees the
+implementation actually keeps.
+
+### Removed (breaking)
+
+- Removed the hidden hyphenated compatibility spellings. Every accepted command
+  is now public and appears in help and shell completion:
+
+  | Removed | Canonical replacement |
+  |---|---|
+  | `save-copy` / `open-copy` | `copy save` / `copy open` |
+  | `build-and-publish` / `finalize-publication` | `publish environment` / `finalize environment` |
+  | `toolchain-publish` / `toolchain-finalize-publication` | `publish toolchain` / `finalize toolchain` |
+  | `toolchain-slim` / `install` | `toolchain slim` / `toolchain install` |
+  | `program-create` / `program-save-copy` / `program-open-copy` / `program-download` | `program create` / `program save` / `program open` / `program download` |
+  | `program-publish` / `program-finalize-publication` | `publish program` / `finalize program` |
+  | `check-file FILE` | `check FILE` (or `run FILE` for standalone discovery) |
+  | `profile ENV FILE` | `check --environment ENV FILE --repeat N` |
+  | `matrix MATRIX FILE` | `check FILE --across MATRIX` |
+  | top-level `scan` / `attach` / `detach` | `project scan` / `project attach` / `project detach` |
+
+- Removed the legacy positional `check ENVIRONMENT FILE` form; use
+  `check --environment NAME FILE`.
+- Removed the deprecated `run` aliases `--discovery-timeout` and `--timeout`;
+  use `--search-timeout` and `--check-timeout`. Removed the undeclared
+  `init --mathlib` alias in favor of `--mathlib-version`.
+- Environment libraries are capsule-only. Removed the legacy full-bundle
+  registry paths: `OCIEnvironmentCache.pull`, `OCIEnvironmentCache.plan`, the
+  full publication profile, and the `DownloadUnavailable` fallbacks in
+  `Runtime.open_exact` and `Runtime.plan_exact`. Publication always writes the
+  `capsule-lock_<sha>` canonical reference, and an environment library object
+  must implement `pull_capsule`/`plan_capsule`. Complete source-bearing
+  environments are unaffected: source builds, `copy save`, and `copy open` all
+  keep working, and `copy open` still reads both archive formats.
+
+### Changed (breaking)
+
+- Program provenance renames `exact_environment_id` to `source_lock_id`
+  (`ProgramDescription`, `Runtime.create_program`, and
+  `program create --source-lock-id`), because the field always held a lock
+  identity. Program copies written with the old key still load.
+
+### Added
+
+- `lean-runtime run FILE` is the canonical front-door spelling. `lean-run`
+  remains a permanently supported alias sharing one parser and implementation,
+  with identical results, envelopes, and exit codes. Global `--home`,
+  `--quiet`, `--verbose`, and `--timings` are accepted both before and after
+  `run`, and global `--library`/`--availability` reach the front door with
+  explicit conflict errors against `--offline` and `--no-source-build`.
+- A misplaced `lean-runtime FILE.lean` invocation suggests `lean-runtime run`.
+- `lean-runtime.plan/v1` ships as an installed schema, and the `check-batch`
+  and `attestation` schemas are registered with the schema resources API.
+
+### Fixed (guarantees)
+
+- `availability="local"` now forbids extending a sparse projection. Missing
+  import closures fail with an actionable error naming the roots instead of
+  silently contacting a configured library.
+- Every path that shells out to Lake installs the full toolchain first
+  (package-graph resolution and materialization, local project probing, and
+  managed build/lake execution), so the documented source fallback no longer
+  breaks after a slim check toolchain has been acquired. Package-free core
+  environments keep their check-only fast path.
+- Capability handling is representation-aware: `native`/`development` requests
+  are a no-op on a full environment and rejected only on a check capsule, and
+  `build()`/`execute()` fail fast on a capsule instead of failing mid-run
+  against incomplete inputs. `Environment.sparse` exposes the representation.
+- Sparse acquisition holds a CAS collection lease across unpacking and
+  projection, so a concurrent `clean --include-downloads` cannot reclaim an
+  artifact that is being projected.
+- `--attest` publishes a versioned `lean-runtime.attestation/v1` predicate
+  carrying the verification report plus a stable `build_inventory` of the Lake
+  build outputs, described by `schemas/attestation-v1.schema.json`.
+- Sparse downloads record the informational platform record in
+  `metadata["platform"]` like every other representation.
+
+### Changed
+
+- `check --repeat` accepts `--environment NAME`, covering everything the
+  removed `profile` command did.
+- Internal dispatch uses canonical command identities (`publish-environment`,
+  `copy-save`, `program-create`, `toolchain-slim`, …) instead of rewriting
+  canonical invocations back onto legacy spellings.
+- Shell completion and top-level help derive from one public command list; the
+  private argparse help-hiding hack is gone. Command help disambiguates the
+  vocabulary across `run`, `check`, `open`, `prepare`, `download`, and `build`.
+- Bundled GitHub workflows and the `publish-environment` composite action use
+  the canonical publication commands.
+- Documentation matches the implementation: corrected
+  `--publisher-verification` spelling, documented `capsule-lock_<sha>`
+  publication references, named the actual verification check codes, scoped the
+  credential-retention claim, noted `lakefile.lean` package-reference support,
+  scoped the closed JSON-envelope claim to the versioned precision surfaces, and
+  replaced "side-effect-free" planning claims with the precise guarantee.
+
+## 2.10.0 - 2026-08-16
+
+- Make header snapshots opt-in (`LEAN_RUNTIME_HEADER_SNAPSHOTS=1`; `--watch` and
+  `--repeat` enable them automatically), key them by module identity, load
+  existing snapshots without holding the creation lock, cancel lock waits
+  promptly, and retry once without a snapshot—quarantining it—when a snapshot
+  check times out or reports snapshot errors.
+- Support `check FILE...` and `check DIRECTORY...` with independent per-file
+  results, `--concurrency`, a `lean-runtime.check-batch/v1` JSON envelope, and
+  an explicit `--environment NAME`; the legacy positional `ENVIRONMENT FILE`
+  form now applies only when the first argument is not an existing path.
+- Attribute shared workspace lock waits to their holder (PID and operation),
+  announce header snapshot waits, and record `workspace_lock` and
+  `header_snapshot` phase timings so coordination cost is visible next to the
+  actual Lean check time.
+
 ## 2.9.2 - 2026-08-16
 
 - Keep one fail-closed publication authentication session from push preflight through

{lean_runtime-2.9.2/lean_runtime.egg-info → lean_runtime-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.9.2
+Version: 3.0.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -57,10 +57,12 @@ currently requires `LEAN_RUNTIME_ELAN`.
 
 ## Run one Lean file
 
-Inside an existing pinned Lake project, just pass the file:
+Lean Runtime's main command is `lean-runtime`; its `run` subcommand discovers a
+context and checks one file. Inside an existing pinned Lake project, just pass
+the file:
 
 ```bash
-lean-run MyProject/Main.lean
+lean-runtime run MyProject/Main.lean
 ```
 
 Standalone files do not need a throwaway Lake project or dependency declaration:
@@ -72,17 +74,21 @@ example : 2 + 2 = 4 := by norm_num
 ```
 
 ```bash
-lean-run Main.lean
+lean-runtime run Main.lean
 ```
 
-When no explicit context or pinned Lake project exists, `lean-run` analyzes imports,
+The shorter `lean-run Main.lean` spelling is an equivalent, permanently
+supported convenience alias; both call the same implementation and produce the
+same results, JSON envelopes, and exit codes.
+
+When no explicit context or pinned Lake project exists, `run` analyzes imports,
 ranks a bounded set of exact environments from its bundled catalog, and asks Lean to
 check each candidate. The successful exact lock is retained by Runtime. Pin it for
 portable reuse whenever desired:
 
 ```bash
-lean-run Main.lean --lock-out environment.lock.json
-lean-run Main.lean --lock environment.lock.json
+lean-runtime run Main.lean --lock-out environment.lock.json
+lean-runtime run Main.lean --lock environment.lock.json
 ```
 
 The bundled catalog covers Mathlib v4.30.0 through v4.33.0 and matching LeanCert
@@ -102,9 +108,10 @@ New-format libraries publish two independently verified pieces: a slim Lean
 check runtime and seekable module packs. Lean Runtime computes the source's
 transitive import closure, downloads only the corresponding compressed frames,
 and shares verified module artifacts across Mathlib, LeanCert, and future
-environments. A warm check is silent apart from its result. Older published
-environments remain readable and automatically use the legacy full-bundle
-path, so this optimization does not invalidate existing locks.
+environments. A warm check is silent apart from its result. Environment
+libraries publish and serve capsules only; a complete source-bearing
+environment is still available locally through a source build or a portable
+copy.
 
 Explicit frontmatter remains available when the desired context is already known:
 
@@ -205,13 +212,15 @@ current exact graph without running `lake update`. If you already have many
 Lake checkouts, register them once as local dependency seeds:
 
 ```bash
-lean-runtime scan ~/research
+lean-runtime project scan ~/research
 lean-runtime init .
 ```
 
-`init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
+`init --plan` performs no downloads, installs, or builds; `--max-download
+500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
-`attach`, and `detach --execute` materializes an independent project again.
+`project attach`, and `project detach --execute` materializes an independent
+project again.
 For a new project, the target may be absent, empty, or an otherwise empty Git
 repository root; existing Git identity and index state are preserved. A custom
 `AGENTS.md` is also allowed and retained. Other existing contents are rejected
@@ -234,8 +243,8 @@ 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
+lean-runtime check --environment research-stack Main.lean --repeat 5
+lean-runtime check Main.lean --across compatibility.toml
 ```
 
 Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/README.md

@@ -21,10 +21,12 @@ currently requires `LEAN_RUNTIME_ELAN`.
 
 ## Run one Lean file
 
-Inside an existing pinned Lake project, just pass the file:
+Lean Runtime's main command is `lean-runtime`; its `run` subcommand discovers a
+context and checks one file. Inside an existing pinned Lake project, just pass
+the file:
 
 ```bash
-lean-run MyProject/Main.lean
+lean-runtime run MyProject/Main.lean
 ```
 
 Standalone files do not need a throwaway Lake project or dependency declaration:
@@ -36,17 +38,21 @@ example : 2 + 2 = 4 := by norm_num
 ```
 
 ```bash
-lean-run Main.lean
+lean-runtime run Main.lean
 ```
 
-When no explicit context or pinned Lake project exists, `lean-run` analyzes imports,
+The shorter `lean-run Main.lean` spelling is an equivalent, permanently
+supported convenience alias; both call the same implementation and produce the
+same results, JSON envelopes, and exit codes.
+
+When no explicit context or pinned Lake project exists, `run` analyzes imports,
 ranks a bounded set of exact environments from its bundled catalog, and asks Lean to
 check each candidate. The successful exact lock is retained by Runtime. Pin it for
 portable reuse whenever desired:
 
 ```bash
-lean-run Main.lean --lock-out environment.lock.json
-lean-run Main.lean --lock environment.lock.json
+lean-runtime run Main.lean --lock-out environment.lock.json
+lean-runtime run Main.lean --lock environment.lock.json
 ```
 
 The bundled catalog covers Mathlib v4.30.0 through v4.33.0 and matching LeanCert
@@ -66,9 +72,10 @@ New-format libraries publish two independently verified pieces: a slim Lean
 check runtime and seekable module packs. Lean Runtime computes the source's
 transitive import closure, downloads only the corresponding compressed frames,
 and shares verified module artifacts across Mathlib, LeanCert, and future
-environments. A warm check is silent apart from its result. Older published
-environments remain readable and automatically use the legacy full-bundle
-path, so this optimization does not invalidate existing locks.
+environments. A warm check is silent apart from its result. Environment
+libraries publish and serve capsules only; a complete source-bearing
+environment is still available locally through a source build or a portable
+copy.
 
 Explicit frontmatter remains available when the desired context is already known:
 
@@ -169,13 +176,15 @@ current exact graph without running `lake update`. If you already have many
 Lake checkouts, register them once as local dependency seeds:
 
 ```bash
-lean-runtime scan ~/research
+lean-runtime project scan ~/research
 lean-runtime init .
 ```
 
-`init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
+`init --plan` performs no downloads, installs, or builds; `--max-download
+500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
-`attach`, and `detach --execute` materializes an independent project again.
+`project attach`, and `project detach --execute` materializes an independent
+project again.
 For a new project, the target may be absent, empty, or an otherwise empty Git
 repository root; existing Git identity and index state are preserved. A custom
 `AGENTS.md` is also allowed and retained. Other existing contents are rejected
@@ -198,8 +207,8 @@ 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
+lean-runtime check --environment research-stack Main.lean --repeat 5
+lean-runtime check Main.lean --across compatibility.toml
 ```
 
 Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/docs/architecture.md

@@ -51,9 +51,9 @@ artifact cache; `Runtime` should not grow a second project build planner.
 Environment capsules, slim toolchains, and ready-to-run programs have distinct
 payload schemas. Their common OCI descriptor, digest, JSON, and platform
 selection contract lives in `oci_protocol`. Payload implementations must not
-import another payload implementation's private protocol helpers. Existing
-legacy bundle readers remain supported, but new transport behavior belongs to
-the shared protocol or the current sparse capsule path.
+import another payload implementation's private protocol helpers. The complete
+portable-copy reader remains supported, but registry transport is capsule-only
+and new behavior belongs to the shared protocol or the sparse capsule path.
 
 ## Public identities
 
@@ -179,12 +179,18 @@ Opening a completed environment by name or digest reads only:
 No resolver or network operation runs. This is tested by deleting the original
 Git repository and reopening/checking the environment from a second process.
 
+For a sparse check capsule, this invariant covers metadata and every already
+projected import closure. Checking a new import extends the projection from a
+configured library, so strictly offline use should pre-acquire the needed
+closure; under `availability="local"` that extension is refused rather than
+downloaded.
+
 ## Aliases and garbage collection
 
 Names are atomic JSON pointers to environment identities. Updating a name does
 not mutate either old or new environments. Garbage collection removes only
 old environments that are not reachable through an alias; locks and source
-snapshots are conservatively retained by store schema 1.
+snapshots are conservatively retained by the current store schema.
 Last-use records prevent recently opened or executed unnamed environments from
 being collected, and execution cloning shares the environment's deletion lock.
 

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/docs/captures.md

@@ -15,7 +15,9 @@ result = Runtime().replay_capture("result.execution.json")
 Captures are manifests, not portable binary archives. They do not currently
 embed Git repositories or compiled artifacts. A clean machine may need network
 access to acquire exact locked commits before its first replay; a machine with
-the environment already published can replay offline.
+the environment already published can replay offline. For a sparse capsule
+environment, offline replay additionally requires the capture's imported
+modules to be projected locally already.
 
 ## Identity semantics
 

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/docs/cli.md

@@ -1,31 +1,40 @@
 # Command-line interface
 
-## `lean-run`
+## `lean-runtime run` and `lean-run`
 
-The front-facing command checks one file and discovers its context:
+The front door discovers a context and checks one file. `lean-runtime run FILE`
+is the canonical main-CLI spelling; `lean-run FILE` is an equivalent
+convenience alias with the same behavior, JSON contracts, and exit codes:
 
 ```bash
+lean-runtime run Main.lean
+lean-runtime run Main.lean --with mathlib@v4.32.2
+lean-runtime run Main.lean --lock environment.lock.json
+lean-runtime run Main.lean --json
+lean-runtime run Main.lean --explain
+lean-runtime run Main.lean --timings
+lean-runtime run Main.lean --lock-out environment.lock.json
+lean-runtime run Main.lean --no-source-build
+lean-runtime run Main.lean --offline
 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
-lean-run Main.lean --lock-out environment.lock.json
-lean-run Main.lean --no-source-build
-lean-run Main.lean --offline
 ```
 
-Without explicit context or a pinned Lake project, `lean-run` automatically
+| Command | Context behavior | Typical use |
+|---|---|---|
+| `lean-runtime run FILE` | Discovers or selects context | Standalone/front door |
+| `lean-run FILE` | Same as `run` | Short convenience spelling |
+| `lean-runtime check FILE` | Requires project or explicit context | Project iteration |
+| `lean-runtime check` | Checks all local libraries | Project-wide check |
+| `lean-runtime build` | Full Lake target build | Executables/native outputs |
+
+Without explicit context or a pinned Lake project, `run` automatically
 searches its bundled exact-environment catalog. Use `--lock-out` to retain the
 successful lock, `--no-discover` to require explicit context, and
 `--catalog PATH` to override the catalog. Three budgets bound the work:
 `--search-timeout` covers ranking and compiler probes, `--check-timeout`
 covers each Lean invocation, and `--acquire-timeout` independently bounds
 downloading, installing, or building one candidate environment, so a slow
-first-time download cannot expire the search. `--discovery-timeout` and
-`--timeout` remain as deprecated aliases of `--search-timeout` and
-`--check-timeout`. See
+first-time download cannot expire the search. See
 [Standalone Lean files](standalone-files.md) for routing and policy details.
 
 ## `lean-runtime`
@@ -33,9 +42,9 @@ first-time download cannot expire the search. `--discovery-timeout` and
 All commands accept `--home PATH` before the subcommand to select a store.
 
 For project iteration, `check FILE --watch` rechecks on save with warm native
-import snapshots. `check FILE --repeat N` measures the same path, and
-`check FILE --across matrix.toml` checks exact contexts. The older `profile`
-and `matrix` commands remain compatibility aliases.
+import snapshots. `check FILE --repeat N` measures the same path (add
+`--environment NAME` to profile inside a managed environment), and
+`check FILE --across matrix.toml` checks exact contexts.
 
 `storage` reads a fingerprinted ledger after its first inventory, so large
 stores remain an instant-information command. `storage --verify` explicitly
@@ -55,7 +64,9 @@ lean-runtime check Main.lean \
 `--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
+`lean-toolchain` and a root Lake configuration (`lakefile.toml` or
+`lakefile.lean`, translated with the package's pinned Lake), 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.
@@ -79,15 +90,15 @@ lean-runtime --home /tmp/fresh copy open research-stack.lean-environment --name
 lean-runtime publish environment environment.lock.json --publish-to ghcr.io/owner/lean-environments
 lean-runtime publish environment --publish-to ghcr.io/owner/lean-environments --check-access
 lean-runtime publish environment --publish-to ghcr.io/owner/lean-environments --check-access --json
-lean-runtime check research-stack Main.lean --json
+lean-runtime check --environment 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 check --environment research-stack Main.lean --repeat 5
+lean-runtime check Main.lean --across matrix.toml
 lean-runtime clean
 lean-runtime clean --execute
 ```
@@ -96,8 +107,7 @@ lean-runtime clean --execute
 
 `copy save` creates a portable environment file. `copy open` verifies its exact
 identity, package Git trees, computer compatibility, and Lean probe before
-making the environment available. The former `save-copy` and `open-copy`
-spellings remain compatibility aliases. See [Portable copies and environment
+making the environment available. See [Portable copies and environment
 libraries](portable-copies.md) for its trust boundary.
 
 ## Slim toolchains
@@ -107,11 +117,11 @@ not need all of it: editor indexes, static libraries, the bundled LLVM/clang,
 and toolchain sources are only used by editors and native compilation.
 
 ```bash
-lean-runtime toolchain-slim v4.32.2
-lean-runtime toolchain-slim v4.32.2 --prune-original
+lean-runtime toolchain slim v4.32.2
+lean-runtime toolchain slim v4.32.2 --prune-original
 ```
 
-`toolchain-slim` materializes a separate check-profile copy by hardlinking the
+`toolchain slim` materializes a separate check-profile copy by hardlinking the
 kept files (near-zero extra disk), then verifies it against a capability
 corpus — elaboration, core tactics, `decide`, `#eval`, metaprogramming, and
 `Std` imports — using the slim copy's own `lean`. A copy that fails any probe
@@ -124,20 +134,21 @@ per-module IR during ordinary elaboration, so those artifact classes must
 stay; larger reductions require upstream facet-loading changes.
 
 After pruning, source builds of *new* environments and native compilation
-need the full toolchain again; reinstall it with `lean-runtime install`.
+need the full toolchain again; reinstall it with `lean-runtime toolchain install`.
 
 Libraries produced by the current publication workflow also carry this
 verified check profile directly. A cold consumer downloads that compressed
 profile instead of first transferring the full official release. If the
 library has no compatible published check runtime, Lean Runtime falls back to
-the official Elan installation path. Local `toolchain-slim` remains useful for
+the official Elan installation path. Local `toolchain slim` remains useful for
 older stores and for testing a profile before publication.
 
 ## Sparse acquisition and capabilities
 
-`lean-run FILE --plan` reads capsule metadata and reports the exact compressed
+`lean-runtime run FILE --plan` reads capsule metadata and reports the exact compressed
 frames required by `FILE`'s transitive import closure, plus the selected Lean
-check-runtime cost. The operation has no store side effects. `--max-download`
+check-runtime cost. The operation performs no downloads, builds, or publications; constructing
+the runtime may still initialize store metadata directories. `--max-download`
 applies before acquisition to the combined known cost; an unknown component is
 reported explicitly instead of treated as zero.
 
@@ -147,7 +158,9 @@ guesswork: Lean 4.32 and 4.33 reject ordinary imports when the corresponding
 server/private or IR facets are omitted. `.ilean` editor indexes are a separate
 on-demand capability through `Environment.require_capabilities(["editor"],
 imports=[...])`. Native compilation and development builds require a full
-environment and full toolchain; check capsules reject those requests clearly.
+environment and full toolchain; a check capsule rejects those capability
+requests, and also rejects `build()` and arbitrary `execute()` before any
+Lean process starts. Open or build the full environment for them.
 
 ## Replay
 
@@ -169,15 +182,15 @@ lean-runtime init MyProof
 lean-runtime init MyProof --core
 lean-runtime init --plan --max-download 500MiB
 lean-runtime update --plan
-lean-runtime scan ~/research
-lean-runtime attach ~/research --recursive
-lean-runtime attach ~/research --recursive --execute
-lean-runtime detach ./existing-project --execute
-lean-runtime install 4.32.2
+lean-runtime project scan ~/research
+lean-runtime project attach ~/research --recursive
+lean-runtime project attach ~/research --recursive --execute
+lean-runtime project detach ./existing-project --execute
+lean-runtime toolchain install 4.32.2
 ```
 
-`check FILE` is the direct standalone/local-project route; the legacy
-`check ENVIRONMENT FILE` spelling remains accepted. When no
+`check FILE` is the direct standalone/local-project route, and
+`check --environment NAME FILE` checks inside a managed environment. 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`.
@@ -211,7 +224,7 @@ capitalization such as `IntegralFramework`.
 Add supporting source files with repeatable `--include` options:
 
 ```bash
-lean-runtime check research-stack Main.lean --include Support/Defs.lean
+lean-runtime check --environment research-stack Main.lean --include Support/Defs.lean
 ```
 
 Resolution and materialization print structured lifecycle progress to stderr.
@@ -256,6 +269,6 @@ self-hosted HTTPS/SSH, and local bare repositories are supported.
 publication and clean-consumer workflow. See
 [Publishing a Lean project](project-publishing.md).
 
-Use global `--publisher_verification required --trusted-publisher ID --trusted-issuer ISSUER`
-to require a verified publisher. `build-and-publish --sign` records the trusted
+Use global `--publisher-verification required --trusted-publisher ID --trusted-issuer ISSUER`
+to require a verified publisher. `publish environment --sign` records the trusted
 publisher using the configured Cosign identity.

{lean_runtime-2.9.2 → lean_runtime-3.0.0}/docs/environments.md

@@ -9,13 +9,17 @@ Lean Runtime separates three states:
 3. `Environment` is a platform-specific, built, published environment.
 
 The separation lets one process resolve a lock and another materialize it. A
-completed environment can subsequently be opened offline.
-
-Downloadable environments may use the legacy full-workspace representation or
-the current sparse check-capsule representation. Both resolve to the same exact
-lock and platform environment identity. A capsule stores a normalized module
-graph and content digest for each Lean artifact; its local projection grows as
-new imports are checked without changing that identity.
+completed environment can subsequently be opened offline; for a sparse
+capsule, checking is offline for already projected import closures, while a
+new import extends the projection from a configured library unless
+`availability="local"` refuses it.
+
+Downloadable environments are sparse check capsules. A capsule stores a
+normalized module graph and content digest for each Lean artifact, resolves to
+the same exact lock and platform environment identity as a locally built
+environment, and its local projection grows as new imports are checked without
+changing that identity. Complete source-bearing environments are still
+produced locally by source builds and exchanged as portable copies.
 
 Package references are an input compiler for `EnvironmentSpec`, not another
 environment type:
@@ -44,7 +48,11 @@ GitPackage(
 - `name` is the Lake package identity.
 - `url` is a Git remote.
 - `rev` is a full commit hash; `GitPackage.tag(...)` and TOML `tag = "..."`
-  provide a friendly input that resolution converts to an exact commit.
+  provide a friendly input that resolution converts to an exact commit. The
+  resolved lock always contains the exact commit and tree, while the
+  requested tag may remain alongside it as requested-revision metadata (and,
+  for manually authored tagged specifications, in the recorded specification
+  digest).
 - `root_module` is imported by the synthetic root library, ensuring the
   dependency's Lean artifacts are built.
 - `subdir` records a safe relative package subdirectory.
@@ -60,7 +68,9 @@ through the locked toolchain.
 The environment identity includes the complete lock, a versioned platform
 compatibility record, and the implemented build profile. Informational details
 such as the Python platform and OS patch release are retained in metadata but
-are not identity inputs. The runtime currently supports only the `release` profile;
+are not identity inputs. Full environments and portable imports record that
+informational platform record; sparse registry downloads currently persist
+only the versioned compatibility record. The runtime currently supports only the `release` profile;
 other values are rejected rather than producing misleadingly distinct IDs for
 identical builds.
 
@@ -105,7 +115,8 @@ CAS and hardlinked into environment projections when the filesystem permits.
 its logical byte count can overlap environment projections and should not be
 added to their logical sizes as an estimate of physical disk use.
 `clean --include-downloads` reclaims old OCI blobs and unleased CAS artifacts;
-per-artifact locks and recency updates prevent collection during projection.
+sparse acquisition holds a collection lease across unpacking and projection,
+so an artifact being projected is never reclaimed.
 
 ```python
 report = runtime.clean(dry_run=True)