lean-runtime 2.7.0__tar.gz → 2.9.0__tar.gz

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## 2.9.0 - 2026-08-15
+
+- Make environment publication fail closed: verify registry push access before
+  building, report the selected credential source, remotely verify every
+  manifest, emit an explicit terminal failure event, and reserve exit codes 3,
+  4, and 5 for permission, retryable transport, and partial/indeterminate
+  publication failures respectively.
+- Make standalone `check FILE` failures point directly to `--toolchain`, and
+  have project checks ask Lake to materialize a missing local import before one
+  automatic retry.
+- Accept any fetchable Git origin for immutable project locks and local exports,
+  including self-hosted and local bare repositories; GitHub origins retain
+  their canonical `github:` convenience reference.
+
+## 2.8.0 - 2026-08-14
+
+- Cut repeated project-check latency with capability-probed Lean header snapshots;
+  `check --watch` rechecks on save, while `check --repeat` and `check --across`
+  absorb the common profile/matrix workflows without removing legacy aliases.
+- Suggest exact-workspace declarations after coded unknown-identifier diagnostics
+  using persisted `.ilean` indexes from the pinned dependency graph.
+- Make `init --mathlib-version VERSION` unambiguous, preserve common repository
+  scaffolding, optionally generate matching CI with `--ci`, and retain the old
+  `--mathlib` spelling as a validated compatibility alias.
+- Add `project scan/attach/detach/update`, `publish KIND`, `finalize KIND`, and
+  `copy save/open` namespaces while retaining existing command spellings for
+  automation.
+- Give environments and doctor human output plus `--json`, add `doctor --fix`,
+  fingerprinted storage accounting with `storage --verify`, cleanup nudges,
+  `clean --keep-last` retention, curated help, and generated Bash/Zsh/Fish
+  completions.
+- Report cumulative frame and byte counters while restoring sparse capsules, so
+  both terse and verbose cold-start output shows measurable forward progress.
+
 ## 2.7.0 - 2026-08-14
 
 - Keep newly initialized project roots narrow: the generated root imports its

{lean_runtime-2.7.0/lean_runtime.egg-info → lean_runtime-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.7.0
+Version: 2.9.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -188,6 +188,7 @@ default, and exact dependencies are shared automatically:
 lean-runtime init MyProof
 cd MyProof
 lean-runtime check MyProof/Basic.lean
+lean-runtime check MyProof/Basic.lean --watch
 # Check every declared local library, in Lake dependency order:
 lean-runtime check
 lean-runtime build
@@ -196,7 +197,7 @@ lean-runtime build
 `init` also writes an `AGENTS.md` with the project build, checking, dependency,
 and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
 existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
-`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+`--mathlib-version 4.33.0` to select a cataloged release. `lean-runtime update`
 explicitly moves a project to the newest cataloged Mathlib after a preview.
 
 Running `lean-runtime init .` in an existing pinned Lake project adopts its
@@ -257,11 +258,17 @@ 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 \
+lean-runtime publish environment environment.lock.json \
   --publish-to ghcr.io/owner/lean-environments
 ```
 
-To publish an existing clean, pushed GitHub Lean project, inspect it and
+Publication verifies push access before doing an expensive build and reports
+which credential source it selected. Run `lean-runtime publish environment
+--publish-to ghcr.io/owner/lean-environments --check-access` to test access by
+itself. A registry denial is a nonzero, machine-distinct failure; success is not
+reported until the remote manifest digest is read back and verified.
+
+To publish an existing clean Git-backed Lean project, inspect it and
 generate the maintained multi-platform workflow:
 
 ```bash

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/README.md

@@ -152,6 +152,7 @@ default, and exact dependencies are shared automatically:
 lean-runtime init MyProof
 cd MyProof
 lean-runtime check MyProof/Basic.lean
+lean-runtime check MyProof/Basic.lean --watch
 # Check every declared local library, in Lake dependency order:
 lean-runtime check
 lean-runtime build
@@ -160,7 +161,7 @@ lean-runtime build
 `init` also writes an `AGENTS.md` with the project build, checking, dependency,
 and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
 existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
-`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+`--mathlib-version 4.33.0` to select a cataloged release. `lean-runtime update`
 explicitly moves a project to the newest cataloged Mathlib after a preview.
 
 Running `lean-runtime init .` in an existing pinned Lake project adopts its
@@ -221,11 +222,17 @@ 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 \
+lean-runtime publish environment environment.lock.json \
   --publish-to ghcr.io/owner/lean-environments
 ```
 
-To publish an existing clean, pushed GitHub Lean project, inspect it and
+Publication verifies push access before doing an expensive build and reports
+which credential source it selected. Run `lean-runtime publish environment
+--publish-to ghcr.io/owner/lean-environments --check-access` to test access by
+itself. A registry denial is a nonzero, machine-distinct failure; success is not
+reported until the remote manifest digest is read back and verified.
+
+To publish an existing clean Git-backed Lean project, inspect it and
 generate the maintained multi-platform workflow:
 
 ```bash

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/docs/cli.md

@@ -32,6 +32,19 @@ 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.
+
+`storage` reads a fingerprinted ledger after its first inventory, so large
+stores remain an instant-information command. `storage --verify` explicitly
+rebuilds that ledger and prints a progress line because it must walk the store.
+`doctor` is human-readable by default; `doctor --json` preserves automation and
+`doctor --fix` applies its safe stale-staging and private-Elan remedies.
+`clean --keep-last N` (or `LEAN_RUNTIME_CLEAN_KEEP_LAST`) retains the newest N
+otherwise eligible unnamed environments in addition to the age threshold.
+
 ## One-shot package workflow
 
 ```bash
@@ -61,9 +74,10 @@ lean-runtime check Main.lean \
 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 copy save research-stack --output research-stack.lean-environment
+lean-runtime --home /tmp/fresh copy open research-stack.lean-environment --name research-stack
+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 check research-stack Main.lean --json
 lean-runtime inspect research-stack --packages
 lean-runtime environments
@@ -79,9 +93,10 @@ 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
+`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. See [Portable copies and environment
+making the environment available. The former `save-copy` and `open-copy`
+spellings remain compatibility aliases. See [Portable copies and environment
 libraries](portable-copies.md) for its trust boundary.
 
 ## Slim toolchains
@@ -211,6 +226,15 @@ 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.
 
+Environment publishing probes repository push access before opening or building
+the lock. `--check-access` runs only that content-free preflight and needs no
+lock. GHCR publishers can use an authenticated `gh` session; explicit
+`LEAN_RUNTIME_REGISTRY_USERNAME` and `LEAN_RUNTIME_REGISTRY_PASSWORD` values take
+precedence. Publication exits `3` for authentication/permission denial, `4` for
+retryable transport or registry failures, and `5` when remote state is partial
+or indeterminate. Success is emitted only after the published manifest is read
+back and its digest is verified. See [Portable copies](portable-copies.md#publishing).
+
 ## Publish an existing project
 
 ```bash
@@ -221,10 +245,12 @@ lean-runtime project init-publish . --module MyProject \
   --library ghcr.io/owner/my-project-environments
 ```
 
-`inspect` is read-only. The other commands require a clean root GitHub project
-whose exact HEAD commit is available from `origin`. `init-publish` creates a
-small caller for the maintained multi-platform publication and clean-consumer
-workflow. See [Publishing a Lean project](project-publishing.md).
+`inspect` is read-only. The other commands require a clean root Git project
+whose exact HEAD commit is available from its configured origin. GitHub,
+self-hosted HTTPS/SSH, and local bare repositories are supported.
+`init-publish` creates a small caller for the maintained multi-platform
+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

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/docs/getting-started.md

@@ -21,17 +21,19 @@ shared exact dependencies:
 lean-runtime init MyProof
 cd MyProof
 lean-runtime check MyProof/Basic.lean
+lean-runtime check MyProof/Basic.lean --watch
 lean-runtime check
 lean-runtime build
 ```
 
 By default, `init` writes an `AGENTS.md` explaining the project workflow and
 shared-dependency safety rules to coding agents. Pass `--no-agents` to omit it.
-An existing file is preserved. The generated root imports only the project's
+An existing file is preserved. Pass `--ci` to generate a workflow that checks
+the same exact committed project graph. The generated root imports only the project's
 local `Basic` module; add the narrow Mathlib imports each implementation file
 needs rather than paying for the all-Mathlib umbrella on every root import.
 
-Use `--mathlib 4.33.0` to select that release explicitly, or `--core` for a
+Use `--mathlib-version 4.33.0` to select that release explicitly, or `--core` for a
 core-only library. The root project remains an ordinary mutable Lake project;
 its dependency sources and build artifacts are reused by other projects with
 the same exact graph.
@@ -81,6 +83,8 @@ lean-runtime scan ~/research
 ```
 
 `scan` only records exact local graphs as possible future zero-download seeds.
+The converged spelling is `lean-runtime project scan`; `project attach`,
+`project detach`, and `project update` group the other dependency-graph actions.
 Advanced bulk migration remains available through `attach`. See [Local Lake
 projects](local-projects.md) for detachment, storage estimates, and the complete
 safety model.
@@ -111,6 +115,11 @@ lean-run Main.lean
 then lets Lean determine which candidate accepts the source. Use
 `--lock-out environment.lock.json` to pin the successful environment.
 
+The lower-level `lean-runtime check Main.lean` command does not guess a
+toolchain for a standalone file. Pass one explicitly, for example
+`lean-runtime check Main.lean --toolchain v4.33.0`, or use `lean-run` for
+catalog discovery.
+
 Strict TOML frontmatter remains available when the context is already known:
 
 ```lean

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/docs/local-projects.md

@@ -29,7 +29,10 @@ lean-runtime check ./my-project/MyProject/Main.lean
 ```
 
 The actual project-relative file is passed to `lake env lean`, so imports of
-local modules retain normal Lake semantics. Checking a source string writes a
+local modules retain normal Lake semantics. A successful file check does not
+itself write that file's `.olean`; if another checked file imports a local
+module whose artifact is missing, Lean Runtime asks Lake to build that module's
+`leanArts` target and retries once. Checking a source string writes a
 uniquely named disposable file under `.lake/lean-runtime/` and removes it after
 execution:
 
@@ -46,6 +49,7 @@ each repository's `.lake/packages`. New projects can start in shared mode:
 lean-runtime init MyProof
 cd MyProof
 lean-runtime check MyProof/Basic.lean
+lean-runtime check MyProof/Basic.lean --watch
 lean-runtime check
 lean-runtime build
 ```
@@ -64,12 +68,19 @@ stays silent. Only root-project outputs enter this cache: locked dependencies
 continue to use the verified shared workspace, avoiding a second multi-gigabyte
 copy. `build` retains Lake's complete target semantics.
 
+Repeated file checks reuse Lean's native header snapshots, keyed by the exact
+toolchain, project identity, and import block. Body-only edits therefore avoid
+reloading the unchanged import environment. `--watch` is a thin save loop over
+the same ordinary check/result contract. Failed checks may add exact-graph
+identifier hints derived from pinned `.ilean` indexes; raw Lean streams remain
+unchanged.
+
 The generated files are a standard Lake project plus a small
 `lean-runtime.toml`. Root build outputs stay local; exact dependencies are
 shared. The generated root imports only its local `Basic` module, leaving
 implementation files free to select precise Mathlib modules. The newest stable
 cataloged Mathlib is selected by default. Select a
-release with `--mathlib 4.33.0`, or use `--core` for a core-only library.
+release with `--mathlib-version 4.33.0`, or use `--core` for a core-only library.
 `init` also creates an `AGENTS.md` describing the safe
 build and dependency workflow unless `--no-agents` is passed; it never
 overwrites an existing guide.

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/docs/portable-copies.md

@@ -113,25 +113,69 @@ Signature failure is an integrity failure and never triggers source fallback.
 
 ## Publishing
 
+Check push access without building or uploading an environment:
+
+```bash
+lean-runtime publish environment \
+  --publish-to ghcr.io/alerad/leancert-runtime \
+  --check-access
+```
+
+For GHCR, credentials are selected in this order: the
+`LEAN_RUNTIME_REGISTRY_USERNAME` / `LEAN_RUNTIME_REGISTRY_PASSWORD` pair, an
+authenticated GitHub CLI session, then anonymous access. The access report names
+the selected account and source but never prints the token. Lean Runtime does not
+implicitly read Docker's credential store. To give the GitHub CLI package access,
+run:
+
+```bash
+gh auth refresh -s write:packages,read:packages
+```
+
 Publish the current platform after ensuring the lock:
 
 ```bash
 export LEAN_RUNTIME_REGISTRY_USERNAME=alerad
 export LEAN_RUNTIME_REGISTRY_PASSWORD="$GHCR_TOKEN"
 
-lean-runtime build-and-publish environment.lock.json \
+lean-runtime publish environment environment.lock.json \
   --publish-to ghcr.io/alerad/leancert-runtime \
   --tag v4.32.2.4 \
   --sign --attest
 ```
 
-The publisher checks for existing blobs, uploads only missing content, publishes
-the platform manifest by digest, and updates the canonical `lock_<sha>` index
-tag last. Human tags are aliases to that same index. This follows the
+The same push-access probe runs automatically before the environment is built,
+so a missing scope fails in seconds instead of after export. The probe starts
+and immediately cancels an empty OCI upload session; it publishes no manifest or
+index. The publisher then checks for existing blobs, uploads only missing
+content, publishes the platform manifest by digest, and updates the canonical
+`lock_<sha>` index tag last. Every manifest is fetched back and its digest is
+verified before success is reported. Human tags are aliases to that same index.
+This follows the
 [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)
 and uses an [OCI image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md)
 for platform selection.
 
+Publication has stable failure codes for CI:
+
+| Exit | Meaning | Retry? |
+|---:|---|---|
+| `2` | Invalid invocation or local input | Fix the invocation |
+| `3` | Registry authentication or permission denial | Fix credentials/scopes first |
+| `4` | Retryable network, throttling, or registry 5xx failure | Yes, with backoff |
+| `5` | Partial or indeterminate publication state | Inspect the terminal state, then retry safely |
+
+An unpublished failure explicitly states that no manifest or index was
+finalized; already uploaded content-addressed blobs are unreferenced and safe to
+reuse on retry. Once a manifest write has been attempted, any failure that
+cannot prove the resulting remote state is reported as partial/indeterminate;
+it is never reported as success. Registries do not use status codes
+uniformly: in particular, GHCR can return 403 for missing permissions as well as
+an inaccessible or not-yet-created package namespace, so diagnostics describe
+these as likely causes rather than certainties. Automation can consume the same
+state from the terminal `library.publish_failed` or `library.published` runtime
+event.
+
 Repository authors can use the bundled composite action after checking out the
 repository and generating or retaining a lock:
 

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/docs/project-publishing.md

@@ -1,6 +1,6 @@
 # Publishing a Lean project
 
-Lean Runtime can freeze a clean, pushed GitHub Lean project into an exact lock,
+Lean Runtime can freeze a clean Git-backed Lean project into an exact lock,
 build it on each supported computer type, and publish verified ready-to-use
 environments through an OCI-compatible library. Consumers import the project's
 public module without cloning or building the project.
@@ -24,7 +24,8 @@ Add `--check-remote` to prove that the exact HEAD commit is available from
 - a root `lakefile.toml` or `lakefile.lean` with an importable Lean library;
 - the Lake project at the Git repository root;
 - a clean checkout;
-- a GitHub `origin`; and
+- a fetchable `origin` (GitHub, self-hosted HTTPS/SSH, `file://`, or a local
+  bare repository); and
 - a HEAD commit available from that remote.
 
 If `lakefile.lean` must be translated, its pinned toolchain must already be
@@ -40,6 +41,12 @@ The default output is `environment.lock.json` in the project root. The lock
 contains the exact project commit, complete Lake dependency graph, toolchain,
 and selected public module.
 
+GitHub HTTPS and SSH origins are canonicalized to the portable HTTPS form and
+receive a `github:OWNER/REPOSITORY@COMMIT` convenience reference. Other origins
+are preserved as exact Git sources. Relative local paths become absolute
+`file://` URLs, which is useful for offline export but intentionally remains
+machine-local unless the resulting capsule is distributed.
+
 ## Export this computer
 
 A portable capsule is useful for transferring the current computer's

{lean_runtime-2.7.0 → lean_runtime-2.9.0}/lean_runtime/__init__.py

@@ -21,6 +21,8 @@ from .errors import (
     MaterializationError,
     PolicyError,
     ProjectError,
+    PublicationError,
+    RegistryRequestError,
     ResolutionError,
     SpecificationError,
     ToolchainError,
@@ -49,7 +51,7 @@ from .models import (
     PhaseTiming,
     ProjectProvenance,
 )
-from .oci import DEFAULT_ENVIRONMENT_LIBRARIES, PublicationInfo
+from .oci import DEFAULT_ENVIRONMENT_LIBRARIES, PublicationAccess, PublicationInfo
 from .policies import ExecutionPolicy
 from .profiling import ProfileReport
 from .programs import ProgramDescription, ProgramInfo, ReadyProgram
@@ -142,6 +144,9 @@ __all__ = [
     "PreparedEnvironment",
     "PolicyError",
     "PublicationInfo",
+    "PublicationAccess",
+    "PublicationError",
+    "RegistryRequestError",
     "DownloadUnavailable",
     "ProjectError",
     "ResolutionError",