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

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

@@ -2,6 +2,20 @@
 
 ## 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;

{lean_runtime-2.8.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.8.0
+Version: 2.9.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -258,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.8.0 → lean_runtime-2.9.0}/README.md

@@ -222,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.8.0 → lean_runtime-2.9.0}/docs/cli.md

@@ -77,6 +77,7 @@ lean-runtime --library ghcr.io/owner/lean-environments download environment.lock
 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
@@ -225,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
@@ -235,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.8.0 → lean_runtime-2.9.0}/docs/getting-started.md

@@ -115,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.8.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:
 

{lean_runtime-2.8.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.8.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.8.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",

{lean_runtime-2.8.0 → lean_runtime-2.9.0}/lean_runtime/cli.py

@@ -15,7 +15,13 @@ from typing import Any, cast
 
 from .console import styler_for
 from .environments import ExecutionCapture
-from .errors import LeanRuntimeError, MaterializationError, ProjectError, ResolutionError
+from .errors import (
+    LeanRuntimeError,
+    MaterializationError,
+    ProjectError,
+    PublicationError,
+    ResolutionError,
+)
 from .events import RuntimeEvent
 from .health import DoctorReport
 from .lake import ROOT_MODULE
@@ -276,6 +282,31 @@ def _print_operation_failure(exc: ResolutionError | MaterializationError, *, ver
         print(exc.output.rstrip(), file=sys.stderr)
 
 
+def _print_publication_failure(exc: PublicationError) -> None:
+    status = f" (HTTP {exc.status_code})" if exc.status_code is not None else ""
+    print(
+        f"✗ Publication failed at {exc.registry} during {exc.phase}{status}",
+        file=sys.stderr,
+    )
+    print(f"  {exc}", file=sys.stderr)
+    identity = exc.username or "anonymous"
+    print(
+        f"  Authentication: {identity} (source: {exc.credential_source})",
+        file=sys.stderr,
+    )
+    if exc.partial:
+        print(
+            "  No verified final release was produced; immutable platform content may exist.",
+            file=sys.stderr,
+        )
+        print("  Safe to retry the publication; verified content will be reused.", file=sys.stderr)
+    else:
+        print("  Nothing was published: no manifest or index was finalized.", file=sys.stderr)
+        print("  Safe to retry; completed blobs will be reused.", file=sys.stderr)
+    if exc.hint:
+        print(f"  Fix: {exc.hint}", file=sys.stderr)
+
+
 def _cli_source_name(path: Path) -> str:
     if path.is_absolute():
         return path.name
@@ -400,7 +431,7 @@ Run `lean-runtime COMMAND --help` for examples and options.""",
     publish = commands.add_parser("publish", help="publish an environment, toolchain, or program")
     publish_kinds = publish.add_subparsers(dest="publish_kind", required=True)
     publish_environment = publish_kinds.add_parser("environment")
-    publish_environment.add_argument("lock", type=Path)
+    publish_environment.add_argument("lock", nargs="?", type=Path)
     publish_environment.add_argument("--publish-to", required=True)
     publish_environment.add_argument("--tag", action="append", default=[])
     publish_environment.add_argument("--name")
@@ -409,6 +440,11 @@ Run `lean-runtime COMMAND --help` for examples and options.""",
     publish_environment.add_argument("--accelerate", action="store_true")
     publish_environment.add_argument("--sign", action="store_true")
     publish_environment.add_argument("--attest", action="store_true")
+    publish_environment.add_argument(
+        "--check-access",
+        action="store_true",
+        help="verify registry push access without building or publishing",
+    )
     publish_toolchain = publish_kinds.add_parser("toolchain")
     publish_toolchain.add_argument("toolchain")
     publish_toolchain.add_argument("--library", required=True)
@@ -464,7 +500,7 @@ Run `lean-runtime COMMAND --help` for examples and options.""",
     push = commands.add_parser(
         "build-and-publish", help="build an exact environment and publish it to a library"
     )
-    push.add_argument("lock", type=Path)
+    push.add_argument("lock", nargs="?", type=Path)
     push.add_argument("--publish-to", required=True)
     push.add_argument("--tag", action="append", default=[])
     push.add_argument("--name")
@@ -490,6 +526,11 @@ Run `lean-runtime COMMAND --help` for examples and options.""",
     push.add_argument(
         "--attest", action="store_true", help="publish a signed source/probe attestation"
     )
+    push.add_argument(
+        "--check-access",
+        action="store_true",
+        help="verify registry push access without building or publishing",
+    )
 
     publish_index = commands.add_parser(
         "finalize-publication", help="combine computer-specific publication results"
@@ -777,7 +818,7 @@ Run `lean-runtime COMMAND --help` for examples and options.""",
     install.add_argument("toolchain")
 
     project = commands.add_parser(
-        "project", help="inspect, freeze, or export a pinned GitHub Lean project"
+        "project", help="inspect, freeze, or export a pinned Git-backed Lean project"
     )
     project_commands = project.add_subparsers(dest="project_command", required=True)
     project_inspect = project_commands.add_parser(
@@ -1144,22 +1185,30 @@ def main(argv: list[str] | None = None) -> int:
             _json(environment.inspect().to_dict())
             return 0
         if args.command == "build-and-publish":
+            access = runtime.check_publication_access(args.publish_to)
+            if args.check_access:
+                _json(access.to_dict())
+                return 0
+            if args.lock is None:
+                raise ValueError("publish environment requires LOCK unless --check-access is used")
             environment = runtime.open_exact(
                 EnvironmentLock.load(args.lock),
                 name=args.name,
                 build_timeout=args.timeout,
                 accelerate=args.accelerate,
             )
-            _json(
-                runtime.publish_environment(
-                    environment.id,
-                    args.publish_to,
-                    tags=args.tag,
-                    finalize=not args.platform_only,
-                    sign=args.sign,
-                    attest=args.attest,
-                ).to_dict()
+            publication = runtime.publish_environment(
+                environment.id,
+                args.publish_to,
+                tags=args.tag,
+                finalize=not args.platform_only,
+                sign=args.sign,
+                attest=args.attest,
+            ).to_dict()
+            publication["consumer_command"] = (
+                f"lean-runtime --library {args.publish_to} download {args.lock}"
             )
+            _json(publication)
             return 0
         if args.command == "finalize-publication":
             descriptors = []
@@ -1631,6 +1680,19 @@ def main(argv: list[str] | None = None) -> int:
         else:
             _print_operation_failure(exc, verbose=args.verbose)
         return 2
+    except PublicationError as exc:
+        if getattr(args, "json", False):
+            _json(
+                envelope(
+                    _schema_for(args.command),
+                    ok=False,
+                    data={"publication": exc.to_dict()},
+                    errors=[error("publication_failed", str(exc), details=exc.to_dict())],
+                )
+            )
+        else:
+            _print_publication_failure(exc)
+        return exc.exit_code
     except (LeanRuntimeError, OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
         if getattr(args, "json", False):
             _json(

{lean_runtime-2.8.0 → lean_runtime-2.9.0}/lean_runtime/errors.py

@@ -64,6 +64,76 @@ class DownloadUnavailable(EnvironmentError):
     """A prebuilt cache had no usable artifact or could not be reached."""
 
 
+class RegistryRequestError(DownloadUnavailable):
+    """An OCI registry request failed with machine-readable retry semantics."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        operation: str,
+        status_code: int | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.operation = operation
+        self.status_code = status_code
+        self.retryable = retryable
+
+
+class PublicationError(EnvironmentError):
+    """A required publication did not reach a remotely verified terminal state."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        phase: str,
+        registry: str,
+        status_code: int | None = None,
+        retryable: bool = False,
+        published: bool = False,
+        partial: bool = False,
+        credential_source: str = "anonymous",
+        username: str | None = None,
+        hint: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.phase = phase
+        self.registry = registry
+        self.status_code = status_code
+        self.retryable = retryable
+        self.published = published
+        self.partial = partial
+        self.credential_source = credential_source
+        self.username = username
+        self.hint = hint
+
+    @property
+    def exit_code(self) -> int:
+        if self.partial:
+            return 5
+        if self.status_code in {401, 403}:
+            return 3
+        if self.retryable:
+            return 4
+        return 5
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "phase": self.phase,
+            "registry": self.registry,
+            "status_code": self.status_code,
+            "retryable": self.retryable,
+            "published": self.published,
+            "partial": self.partial,
+            "credential_source": self.credential_source,
+            "username": self.username,
+            "hint": self.hint,
+            "message": str(self),
+        }
+
+
 class DownloadLimitExceeded(EnvironmentError):
     """An acquisition needs more bytes than the configured download limit.