lean-runtime 2.6.0__tar.gz → 2.6.2__tar.gz

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 2.6.2 - 2026-08-14
+
+- Keep an existing initialization target's directory inode alive, so running
+  `lean-runtime init .` no longer strands the invoking shell in an unlinked
+  working directory. Fully prepared staged children are published with rollback
+  while Git metadata, custom agent guidance, and index state remain in place.
+- Make attachment plans distinguish checkout bytes removed, compatible shared
+  bytes already available, new shared bytes required, and estimated machine
+  recovery. Exact managed packages now bypass redundant source resolution when
+  their toolchain, platform, revision, and effective dependency closure match.
+- Emit package-by-package shared-workspace resolution, reuse, and import events,
+  and add `lean-runtime --version`.
+
+## 2.6.1 - 2026-08-14
+
+- Allow `lean-runtime init .` at an otherwise empty Git repository root while
+  preserving its original `.git` directory or worktree file, HEAD, and index.
+  Planning and execution now share target validation, so `init --plan` rejects
+  unsupported existing contents before reporting an acquisition-ready plan.
+- Add `init --name NAME` for repository directories whose filesystem spelling
+  should not determine the Lake package and Lean root module name. Repeating
+  the same named initialization is idempotent; a conflicting name is rejected.
+- Make `init --plan --offline` and `update --plan --offline` genuinely
+  network-free. Plans now report explicit blockers and return a failing status
+  when an exact local graph or required full toolchain is unavailable.
+
 ## 2.6.0 - 2026-08-14
 
 - Make the local-project path a four-command workflow: `init`, `check`,

{lean_runtime-2.6.0/lean_runtime.egg-info → lean_runtime-2.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.6.0
+Version: 2.6.2
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -209,6 +209,14 @@ lean-runtime init .
 `init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
 `attach`, and `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
+before acquisition rather than overwritten.
+An existing target directory remains the same live directory, so `init .` does
+not invalidate the invoking shell's working directory.
+When the directory spelling is not the intended Lean module capitalization,
+set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 
 One-shot helpers are available when setup reuse is unnecessary:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/README.md

@@ -173,6 +173,14 @@ lean-runtime init .
 `init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
 `attach`, and `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
+before acquisition rather than overwritten.
+An existing target directory remains the same live directory, so `init .` does
+not invalidate the invoking shell's working directory.
+When the directory spelling is not the intended Lean module capitalization,
+set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 
 One-shot helpers are available when setup reuse is unnecessary:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/docs/cli.md

@@ -176,6 +176,21 @@ recursive mode inventories a project tree, reports blockers and estimated disk
 recovery, and adopts each valid project transactionally. `detach` is likewise a
 preview unless `--execute` is present. Attached projects use shared mode by
 default in `lean-runtime build`; detach before requesting `--local`.
+The attachment preview separates bytes removed from each checkout, compatible
+bytes already present in the shared store, new shared bytes that must be
+imported, and estimated machine-level recovery. These quantities differ on a
+first attachment because copy-on-write migration can shrink the repository
+without immediately freeing the dependency blocks retained by the shared copy.
+
+A new `init` target may be absent, empty, or an otherwise empty Git root, with
+an optional existing `AGENTS.md`. Git metadata and the custom guide are
+preserved. Planning rejects any other existing contents using the same
+validation as execution.
+Existing target directories are populated in place after staging verifies, so
+`lean-runtime init .` keeps the caller's current working directory valid.
+`--name NAME` overrides the inferred Lake package/root module name for a new
+project, which is useful when a lowercase repository name needs internal
+capitalization such as `IntegralFramework`.
 
 Add supporting source files with repeatable `--include` options:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/docs/getting-started.md

@@ -37,10 +37,29 @@ Before doing any work, `init --plan` reports the exact release, local reuse, and
 known download size. `--max-download 500MiB` refuses a larger transfer and
 `--offline` requires a matching local graph. Initialization is transactional:
 the target appears only after Lake and the shared dependency graph both verify.
+Offline plans perform no registry lookup; they return a blocked plan and a
+nonzero status when the required exact local graph is absent.
 Project development requires one full Lake-capable Lean toolchain per Lean
 version. When it is absent, the plan says its Elan download size is unknown;
 `--offline` and `--max-download` fail closed instead of silently installing it.
 
+The target may be a missing directory, an empty directory, or an otherwise
+empty Git repository root. In the Git case, `init` preserves the existing HEAD,
+index, remotes, and worktree metadata. It also preserves an existing
+`AGENTS.md`; any other non-project contents are rejected by both `--plan` and
+execution rather than overwritten.
+If the target already exists, initialization keeps that directory inode alive;
+the shell that runs `lean-runtime init .` can immediately continue using it.
+The directory name normally supplies the Lake package/root module name. Override
+it when capitalization matters, for example:
+
+```bash
+lean-runtime init . --name IntegralFramework
+```
+
+The same command can be rerun safely after initialization; a different name is
+rejected rather than silently renaming an existing project.
+
 Dependency upgrades are explicit:
 
 ```bash

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/docs/local-projects.md

@@ -61,11 +61,23 @@ Initialization acquires and verifies the exact graph before publishing the
 target directory. Use `--plan` for a side-effect-free cost report, `--offline`
 to require local data, `--max-download SIZE` to enforce a transfer ceiling, or
 `--seed-from PROJECT` to name an exact local donor.
+Offline planning never queries configured registries. A missing exact local
+graph appears as a blocker and makes the planning command fail.
 The plan separately reports whether the full Lake-capable toolchain is already
 installed. Because Elan does not publish a preflight byte count, a missing full
 toolchain is rejected under `--offline` or `--max-download` rather than silently
 bypassing the policy.
 
+An otherwise empty Git root is a valid new-project target. The original `.git`
+directory—or `.git` worktree file—stays in place without changing HEAD, the
+index, or remotes. The existing directory inode also stays live, so invoking
+`lean-runtime init .` does not strand the shell in an unlinked working
+directory. A pre-existing `AGENTS.md` is preserved. Other contents must be moved
+first or represented by an existing pinned Lake project; the read-only plan
+enforces the same rule as execution.
+Use `--name NAME` when creating inside a lowercase or otherwise differently
+named repository and the Lean root module needs an explicit spelling.
+
 For an existing pinned project, `lean-runtime init .` adopts its current
 manifest without changing versions. Register a collection once with
 `lean-runtime scan ~/research`; future exact matches are preferred over
@@ -96,13 +108,15 @@ lean-runtime attach ~/research --recursive
 lean-runtime attach ~/research --recursive --execute
 ```
 
-The preview groups exact graphs, reports current and estimated shared storage,
-and identifies missing local paths, dirty dependencies, and revision
-mismatches. Execution continues through independent projects while reporting
-per-project failures. It first prepares the exact shared workspace and probes it
-through Lake. Only then does it atomically replace `.lake/packages` with package
-links, probe the resulting project through ordinary Lake, and discard the old
-generated copies. Any failure restores the original package directory.
+The preview groups exact graphs and separately reports checkout bytes removed,
+compatible shared bytes already ready, new shared bytes required, and estimated
+machine-level recovery. It also identifies missing local paths, dirty
+dependencies, and revision mismatches. Execution continues through independent
+projects while reporting per-project failures. It first prepares the exact
+shared workspace and probes it through Lake. Only then does it atomically
+replace `.lake/packages` with package links, probe the resulting project through
+ordinary Lake, and discard the old generated copies. Any failure restores the
+original package directory.
 
 The project itself remains portable. To return to independent package copies:
 
@@ -141,12 +155,20 @@ their artifacts.
 
 The first shared build imports a clean, revision-matching local dependency copy
 when one exists, using copy-on-write filesystem clones where supported. Missing
-sources are fetched at the exact manifest commit. A plain shared build never
+sources are fetched at the exact manifest commit. A later project bypasses
+source resolution when a managed package marker proves that its toolchain,
+platform, revision, and effective dependency closure already match. A plain shared build never
 deletes the old `.lake/packages`; only an explicit `attach --execute` replaces
 those generated copies after verification. `lean-runtime storage` reports
 shared project package usage; automatic cleanup of those packages is not yet
 implemented.
 
+Check capsules and mutable shared packages are intentionally separate storage
+tiers. Capsules are source-free and trimmed for checking; ordinary Lake
+development needs source-shaped packages and build metadata. A capsule can seed
+compatible build artifacts while the exact source workspace is materialized,
+but attached projects ultimately link to the mutable shared-project store.
+
 This mode requires a manifest and never runs `lake update`, so it cannot silently
 change dependency revisions. It also reuses an existing local Git object database
 when that database contains another requested revision, avoiding redundant Git

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/lean_runtime/cli.py

@@ -7,12 +7,13 @@ import json
 import sys
 import time
 from datetime import datetime
+from importlib.metadata import version as distribution_version
 from pathlib import Path
 from typing import Any
 
 from .console import styler_for
 from .environments import ExecutionCapture
-from .errors import LeanRuntimeError, MaterializationError, ResolutionError
+from .errors import LeanRuntimeError, MaterializationError, ProjectError, ResolutionError
 from .events import RuntimeEvent
 from .lake import ROOT_MODULE
 from .lockfiles import EnvironmentLock
@@ -172,9 +173,12 @@ def _render_adoption_plan(plan: AdoptionPlan) -> None:
         for warning in project.warnings:
             print(f"           note: {warning}")
     print()
-    print(f"Current dependency copies: {format_byte_size(plan.current_dependency_bytes)}")
-    print(f"Estimated shared copies:   {format_byte_size(plan.estimated_shared_bytes)}")
-    print(f"Potential recovery:        {format_byte_size(plan.estimated_reclaimable_bytes)}")
+    print(f"Checkout bytes removed:    {format_byte_size(plan.checkout_bytes_removed)}")
+    print(f"Shared bytes already ready:{format_byte_size(plan.shared_bytes_reused):>10}")
+    print(f"New shared bytes needed:   {format_byte_size(plan.new_shared_bytes)}")
+    print(
+        f"Estimated machine recovery: {format_byte_size(plan.estimated_machine_reclaimable_bytes)}"
+    )
 
 
 def _render_init_plan(plan: ProjectInitPlan) -> None:
@@ -184,7 +188,8 @@ def _render_init_plan(plan: ProjectInitPlan) -> None:
         print(f"Exact dependencies: {len(plan.packages)} package(s); versions unchanged")
         return
     context = f"Mathlib {plan.mathlib_version}" if plan.mathlib_version else "core Lean"
-    print(f"Create {plan.root.name} · {context} · {plan.toolchain}")
+    name = plan.project_name or plan.root.name
+    print(f"Create {name} in {plan.root} · {context} · {plan.toolchain}")
     if not plan.toolchain_installed:
         print("Full Lake toolchain: download required (size not published by Elan)")
     if plan.seed_root is not None:
@@ -194,6 +199,8 @@ def _render_init_plan(plan: ProjectInitPlan) -> None:
         print(f"Download: {format_byte_size(plan.download_bytes)}")
     else:
         print("Download: unknown (no compatible published artifact could be priced)")
+    for blocker in plan.blockers:
+        print(f"Blocker: {blocker}")
 
 
 def _render_update_plan(plan: ProjectUpdatePlan) -> None:
@@ -277,6 +284,11 @@ def _add_policy(parser: argparse.ArgumentParser, *, timeout: float = 120) -> Non
 
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser(prog="lean-runtime")
+    root.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {distribution_version('lean-runtime')}",
+    )
     root.add_argument("--home", help="runtime store root")
     root.add_argument("--quiet", action="store_true", help="suppress progress events")
     root.add_argument("--verbose", action="store_true", help="show detailed decisions and checks")
@@ -538,6 +550,7 @@ def parser() -> argparse.ArgumentParser:
         "init", help="create a latest-Mathlib project or adopt an existing Lake project"
     )
     init.add_argument("path", type=Path, nargs="?", default=Path("."))
+    init.add_argument("--name", help="explicit Lake package and root module name")
     init_context = init.add_mutually_exclusive_group()
     init_context.add_argument(
         "--mathlib",
@@ -666,6 +679,7 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "init":
             init_plan = runtime.plan_project_init(
                 args.path,
+                name=args.name,
                 mathlib=args.mathlib,
                 toolchain=args.toolchain,
                 seed_from=args.seed_from,
@@ -675,11 +689,16 @@ def main(argv: list[str] | None = None) -> int:
                     _json(init_plan.to_dict())
                 else:
                     _render_init_plan(init_plan)
-                return 0
+                return 0 if init_plan.ready else 1
+            if not init_plan.ready:
+                raise ProjectError(
+                    "project cannot be initialized:\n- " + "\n- ".join(init_plan.blockers)
+                )
             if not args.json:
                 _render_init_plan(init_plan)
             init_result = runtime.init_project(
                 args.path,
+                name=args.name,
                 mathlib=args.mathlib,
                 toolchain=args.toolchain,
                 agents=args.agents,
@@ -737,7 +756,11 @@ def main(argv: list[str] | None = None) -> int:
                     _render_adoption_plan(adoption_plan)
                     print("No changes made. Re-run with --execute to adopt shared packages.")
                 return 0 if adoption_plan.blocked == 0 else 1
-            adoption_result = runtime.attach_projects(args.path, recursive=args.recursive)
+            adoption_result = runtime.attach_projects(
+                args.path,
+                recursive=args.recursive,
+                plan=adoption_plan,
+            )
             if args.json:
                 _json(adoption_result.to_dict())
             else:

{lean_runtime-2.6.0 → lean_runtime-2.6.2}/lean_runtime/project_sharing.py

@@ -156,6 +156,8 @@ class AdoptionPlan:
     recursive: bool
     current_dependency_bytes: int
     estimated_shared_bytes: int
+    shared_bytes_reused: int = 0
+    new_shared_bytes: int = 0
 
     @property
     def ready(self) -> int:
@@ -167,7 +169,16 @@ class AdoptionPlan:
 
     @property
     def estimated_reclaimable_bytes(self) -> int:
-        return max(0, self.current_dependency_bytes - self.estimated_shared_bytes)
+        """Compatibility alias for estimated machine-level recovery."""
+        return self.estimated_machine_reclaimable_bytes
+
+    @property
+    def checkout_bytes_removed(self) -> int:
+        return self.current_dependency_bytes
+
+    @property
+    def estimated_machine_reclaimable_bytes(self) -> int:
+        return max(0, self.current_dependency_bytes - self.new_shared_bytes)
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -177,6 +188,10 @@ class AdoptionPlan:
             "blocked": self.blocked,
             "current_dependency_bytes": self.current_dependency_bytes,
             "estimated_shared_bytes": self.estimated_shared_bytes,
+            "checkout_bytes_removed": self.checkout_bytes_removed,
+            "shared_bytes_reused": self.shared_bytes_reused,
+            "new_shared_bytes": self.new_shared_bytes,
+            "estimated_machine_reclaimable_bytes": (self.estimated_machine_reclaimable_bytes),
             "estimated_reclaimable_bytes": self.estimated_reclaimable_bytes,
         }
 
@@ -232,6 +247,12 @@ class ProjectInitPlan:
     download_bytes_complete: bool
     already_attached: bool = False
     toolchain_installed: bool = False
+    project_name: str | None = None
+    blockers: tuple[str, ...] = ()
+
+    @property
+    def ready(self) -> bool:
+        return not self.blockers
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -245,6 +266,9 @@ class ProjectInitPlan:
             "download_bytes_complete": self.download_bytes_complete,
             "already_attached": self.already_attached,
             "toolchain_installed": self.toolchain_installed,
+            "project_name": self.project_name,
+            "ready": self.ready,
+            "blockers": list(self.blockers),
         }
 
 
@@ -393,10 +417,16 @@ def inspect_adoption(root: Path) -> ProjectAdoption:
     )
 
 
-def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
+def plan_adoption(
+    path: Path,
+    *,
+    recursive: bool,
+    shared: SharedProjectManager | None = None,
+) -> AdoptionPlan:
     roots = discover_shareable_projects(path, recursive=recursive)
     projects = tuple(inspect_adoption(root) for root in roots)
     groups: dict[str, int] = {}
+    reused_groups: set[str] = set()
     for project in projects:
         if not project.ready or project.attached:
             continue
@@ -408,6 +438,15 @@ def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
             str(entry["name"]): _entry_identity(identity_entry)
             for entry, identity_entry in zip(entries, identity_entries, strict=True)
         }
+        reusable = (
+            shared.reusable_packages(
+                context,
+                entries,
+                effective_entries=effective_entries,
+            )
+            if shared is not None
+            else {}
+        )
         package_dir = _packages_directory(context)
         for entry in entries:
             if entry["type"] != "git":
@@ -416,23 +455,30 @@ def plan_adoption(path: Path, *, recursive: bool) -> AdoptionPlan:
             local_bytes = _tree_bytes(local)
             subdir = entry.get("subDir")
             source_package = local / subdir if isinstance(subdir, str) and subdir else local
-            if _git_head(local) == entry.get("rev") and source_package.is_dir():
+            reusable_package = reusable.get(str(entry["name"]))
+            if reusable_package is not None:
+                key = reusable_package.name
+                reused_groups.add(key)
+            elif _git_head(local) == entry.get("rev") and source_package.is_dir():
                 identity = _package_identity(
                     context=context,
                     entry=entry,
                     source_package=source_package,
                     effective_entries=effective_entries,
                 )
+                key = sha256_id("project_package", identity)
             else:
                 identity = {
                     "toolchain": context.toolchain,
                     "manifest": manifest,
                     "package": entry,
                 }
-            key = sha256_id("project_adoption_estimate", identity)
+                key = sha256_id("project_adoption_estimate", identity)
             groups[key] = max(groups.get(key, 0), local_bytes)
     current = sum(project.dependency_bytes for project in projects if not project.attached)
-    return AdoptionPlan(projects, recursive, current, sum(groups.values()))
+    reused = sum(size for key, size in groups.items() if key in reused_groups)
+    new = sum(size for key, size in groups.items() if key not in reused_groups)
+    return AdoptionPlan(projects, recursive, current, sum(groups.values()), reused, new)
 
 
 def plan_detachment(root: Path) -> DetachmentPlan:
@@ -490,6 +536,12 @@ class ProjectAdopter:
             seed_packages=seed_packages,
             seed_package_paths=seed_package_paths,
         )
+        self.shared.events.emit(
+            "project.attach.shared_probe_started",
+            f"Verifying shared graph for {context.root.name}",
+            phase="project-attach",
+            packages=len(workspace.package_ids),
+        )
         probe(workspace.overrides_file)
         manifest_packages = _manifest_packages(context)
         override_value = json.loads(workspace.overrides_file.read_text(encoding="utf-8"))
@@ -516,6 +568,13 @@ class ProjectAdopter:
         marker = lake_dir / ATTACHMENT_RECORD
         config = context.root / PROJECT_CONFIG
         try:
+            self.shared.events.emit(
+                "project.attach.swap_started",
+                f"Replacing local dependency copies for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+                checkout_bytes=reclaimed,
+            )
             for entry in manifest_packages:
                 if entry["type"] != "git":
                     continue
@@ -535,6 +594,12 @@ class ProjectAdopter:
                 packages_dir.replace(backup)
             staging.replace(packages_dir)
             swapped = True
+            self.shared.events.emit(
+                "project.attach.attached_probe_started",
+                f"Verifying attached graph for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+            )
             probe(None)
             record = {
                 "schema": ATTACHMENT_SCHEMA,
@@ -547,6 +612,13 @@ class ProjectAdopter:
             write_json_atomic(marker, record)
             config.write_text(_CONFIG_CONTENT, encoding="utf-8")
             _remove_path(backup)
+            self.shared.events.emit(
+                "project.attach.completed",
+                f"Attached shared dependencies for {context.root.name}",
+                phase="project-attach",
+                packages=len(workspace.package_ids),
+                checkout_bytes=reclaimed,
+            )
         except BaseException:
             _remove_path(staging)
             if swapped: