lean-runtime 2.3.0__tar.gz → 2.5.0__tar.gz

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 2.5.0 - 2026-08-14
+
+- Make `lean-runtime init` create a concise `AGENTS.md` with build, checking,
+  and shared-dependency safety instructions by default. `--no-agents` opts out,
+  and existing guides are preserved.
+- Make `scripts/release.sh` provision an isolated release environment and allow
+  safe retries after a pre-tag failure instead of depending on undeclared
+  packages in the invoking Python environment.
+
+- Add shared Lake project onboarding and migration. `lean-runtime init` creates
+  a standard core or cataloged-Mathlib project; `attach` previews or
+  transactionally adopts one project or an entire recursive tree; and `detach`
+  materializes independent copies again. Adoption preserves root build output,
+  rejects dirty or mismatched dependencies, verifies both generated overrides
+  and ordinary Lake package links, and rolls back failed swaps. Attached
+  projects automatically use shared mode in `lean-runtime build`.
+- Add content-addressed Lake dependency workspaces. Each exact package is reused
+  across root manifests when its effective transitive closure, toolchain, and
+  platform match. Concurrent runtime builds are serialized, existing clean
+  artifacts seed the store with copy-on-write clones, and local Git object
+  databases seed other revisions without another network clone. Plain
+  `build --shared` never modifies the checkout; only explicit
+  `attach --execute` removes verified generated duplicates.
+
+- Add versioned check capsules: publisher-built manifests record every retained
+  module facet, exact import edges, content digest, package owner, and
+  capability. Publication now fails unless the full environment and a
+  physically isolated capsule both accept the locked public import.
+- Replace monolithic environment pulls with deterministic seekable zstd packs.
+  A clean check downloads only the pack frames covering its transitive import
+  closure; verified raw artifacts are shared in a cross-environment CAS and
+  projected atomically. `lean-run --plan` reports closure and check-runtime
+  costs before transfer, and `--max-download` gates their combined known cost.
+- Publish independently verified check-only Lean toolchains through the same
+  multi-platform OCI library. Consumers prefer the slim signed runtime before
+  installing the full official toolchain, while retaining an Elan fallback for
+  libraries that have not published the new artifact yet.
+- Add explicit sparse capabilities. Batch checking includes every olean facet
+  and IR file Lean actually requires; editor indexes are acquired only when
+  requested. Native/development requests fail with an actionable full-build
+  requirement instead of pretending that a check capsule supports them.
+- Make project export source-free and closure-scoped. `project export` now
+  creates a portable sparse capsule, and `open-copy` verifies its OCI digest
+  chain, per-artifact CAS hashes, exact lock/platform identity, and Lean probe
+  before publishing it locally.
+- Include shared sparse artifacts in `lean-runtime storage` and safely reclaim
+  old unleased CAS entries with `clean --include-downloads`.
+- Make releases tag-driven and fail closed: the helper waits for CI on the exact
+  release commit; the tag workflow independently checks version, changelog,
+  tests, docs, wheel metadata, and wheel installation; PyPI must succeed before
+  the GitHub release is created.
 - Extend the bundled catalog through Mathlib v4.33.0 and add exact LeanCert
   environments for the supported Lean 4.30, 4.31, 4.32, and 4.33 lines.
   Otherwise-equivalent discovery candidates now prefer the smallest exact

{lean_runtime-2.3.0/lean_runtime.egg-info → lean_runtime-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.3.0
+Version: 2.5.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -22,6 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: tomli>=2; python_version < "3.11"
+Requires-Dist: zstandard<1,>=0.23
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -90,6 +91,21 @@ environment libraries, then builds the exact source environment when necessary.
 `--no-source-build` to forbid that potentially large fallback or `--offline` to use
 retained environments only.
 
+Before a cold run, inspect its cost without changing the store:
+
+```bash
+lean-run Main.lean --plan
+lean-run Main.lean --max-download 2GiB
+```
+
+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.
+
 Explicit frontmatter remains available when the desired context is already known:
 
 ```lean
@@ -165,6 +181,32 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
+Create a normal Lake project whose exact dependencies are shared automatically:
+
+```bash
+lean-runtime init MyProof --mathlib
+cd MyProof
+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.
+
+Existing repositories can preview and adopt the same layout individually or in
+bulk:
+
+```bash
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+```
+
+The dry run reports blockers and estimated recovery without changing anything.
+Adoption preserves each root `.lake/build`, verifies both the override and
+ordinary Lake views, then replaces only generated package copies with links to
+the content-addressed store. `lean-runtime detach . --execute` materializes an
+independent project again.
+
 One-shot helpers are available when setup reuse is unnecessary:
 
 ```python
@@ -217,7 +259,9 @@ lean-runtime project init-publish . \
 ```
 
 The workflow builds and verifies Linux and macOS environments, finalizes the
-index atomically, then checks clean consumers. See
+environment and slim-toolchain indexes atomically, then checks clean consumers.
+For a one-machine handoff, `lean-runtime project export` writes a source-free
+portable capsule containing only the selected public module's closure. See
 [Publishing a Lean project](https://alerad.github.io/lean-runtime/project-publishing/).
 
 For an already-built executable, Lean Runtime can also create a verified
@@ -229,10 +273,10 @@ library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-downloadable environment reuse, replayable provenance, verification, and trusted
-publishers. The libraries use OCI-compatible storage internally, but users do
-not need Docker or container concepts. Advanced protocol details remain in the
-architecture documentation.
+downloadable environment reuse, sparse content-addressed module packs,
+replayable provenance, verification, and trusted publishers. The libraries use
+OCI-compatible storage internally, but users do not need Docker or container
+concepts. Advanced protocol details remain in the architecture documentation.
 
 ## Documentation
 

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/README.md

@@ -55,6 +55,21 @@ environment libraries, then builds the exact source environment when necessary.
 `--no-source-build` to forbid that potentially large fallback or `--offline` to use
 retained environments only.
 
+Before a cold run, inspect its cost without changing the store:
+
+```bash
+lean-run Main.lean --plan
+lean-run Main.lean --max-download 2GiB
+```
+
+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.
+
 Explicit frontmatter remains available when the desired context is already known:
 
 ```lean
@@ -130,6 +145,32 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
+Create a normal Lake project whose exact dependencies are shared automatically:
+
+```bash
+lean-runtime init MyProof --mathlib
+cd MyProof
+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.
+
+Existing repositories can preview and adopt the same layout individually or in
+bulk:
+
+```bash
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+```
+
+The dry run reports blockers and estimated recovery without changing anything.
+Adoption preserves each root `.lake/build`, verifies both the override and
+ordinary Lake views, then replaces only generated package copies with links to
+the content-addressed store. `lean-runtime detach . --execute` materializes an
+independent project again.
+
 One-shot helpers are available when setup reuse is unnecessary:
 
 ```python
@@ -182,7 +223,9 @@ lean-runtime project init-publish . \
 ```
 
 The workflow builds and verifies Linux and macOS environments, finalizes the
-index atomically, then checks clean consumers. See
+environment and slim-toolchain indexes atomically, then checks clean consumers.
+For a one-machine handoff, `lean-runtime project export` writes a source-free
+portable capsule containing only the selected public module's closure. See
 [Publishing a Lean project](https://alerad.github.io/lean-runtime/project-publishing/).
 
 For an already-built executable, Lean Runtime can also create a verified
@@ -194,10 +237,10 @@ library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-downloadable environment reuse, replayable provenance, verification, and trusted
-publishers. The libraries use OCI-compatible storage internally, but users do
-not need Docker or container concepts. Advanced protocol details remain in the
-architecture documentation.
+downloadable environment reuse, sparse content-addressed module packs,
+replayable provenance, verification, and trusted publishers. The libraries use
+OCI-compatible storage internally, but users do not need Docker or container
+concepts. Advanced protocol details remain in the architecture documentation.
 
 ## Documentation
 

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/architecture.md

@@ -114,6 +114,29 @@ renames the stage to its final identity.
 Crashes cannot publish a partially ready environment. Concurrent processes
 requesting the same identity converge on the same published directory.
 
+## Check capsules and sparse acquisition
+
+Publication derives a normalized capsule manifest from the authoritative full
+build with the selected Lean version's import parser. Each module records exact
+imports and all retained artifact facets. The publisher physically projects a
+source-free copy and requires both the full build and that isolated projection
+to accept the locked public import before it can upload anything.
+
+Artifacts are grouped by package and capability into deterministic zstd packs.
+Each pack is a sequence of independently compressed and hashed frames; the OCI
+manifest still addresses the complete pack, while consumers use exact HTTP
+Range requests for only the frames intersecting a source's transitive import
+closure. Decompressed artifacts are verified into a raw-content CAS and
+hardlinked into a growing environment projection. The generated versioned
+`--setup` file points Lean directly at those facets, bypassing Lake and source
+metadata during checks.
+
+The Lean executable and core libraries use a separate multi-platform check
+toolchain index keyed by normalized toolchain identity. Platform selection is
+encoded only in child descriptors, so one atomic index serves Linux AMD64,
+macOS AMD64, and macOS ARM64. Consumers verify the exact Lean commit and run a
+capability corpus before publishing the downloaded runtime locally.
+
 ## Execution
 
 A published build is not used as an ordinary mutable working directory. Each

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/cli.md

@@ -109,8 +109,29 @@ 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`.
-Downloads are unaffected: first-time installation still transfers the full
-official release before a slim copy can be derived from it.
+
+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
+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
+frames required by `FILE`'s transitive import closure, plus the selected Lean
+check-runtime cost. The operation has no store side effects. `--max-download`
+applies before acquisition to the combined known cost; an unknown component is
+reported explicitly instead of treated as zero.
+
+The ordinary check capability retains `.olean`, `.olean.server`,
+`.olean.private`, `.ir`, and `.ir.sig`. This is empirical, not conservative
+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.
 
 ## Replay
 
@@ -128,6 +149,11 @@ environment can replay offline.
 lean-runtime check-file Main.lean --toolchain 4.32.2
 lean-runtime check-file ./existing-project/MyProject/Main.lean
 lean-runtime build ./existing-project MyLibrary
+lean-runtime init MyProof --mathlib
+lean-runtime init MyProof --mathlib --no-agents
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+lean-runtime detach ./existing-project --execute
 lean-runtime install 4.32.2
 ```
 
@@ -137,6 +163,13 @@ identifier. `check-file` is the direct local-project route. When no
 containing a Lake configuration and `lean-toolchain`, then passes the actual
 project-relative file to `lake env lean`.
 
+`init` creates a standard core or Mathlib Lake library and attaches its exact
+cataloged dependencies. `attach` is read-only unless `--execute` is present;
+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`.
+
 Add supporting source files with repeatable `--include` options:
 
 ```bash

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/environments.md

@@ -11,6 +11,12 @@ Lean Runtime separates three states:
 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.
+
 Package references are an input compiler for `EnvironmentSpec`, not another
 environment type:
 
@@ -87,6 +93,14 @@ Short-lived execution leases prevent deletion during cloning without
 serializing concurrent checks. Locks and source snapshots remain retained in
 the current store schema.
 
+Sparse downloads are stored once by artifact digest under the shared module
+CAS and hardlinked into environment projections when the filesystem permits.
+`lean-runtime storage` reports this category separately. Because it is shared,
+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.
+
 ```python
 report = runtime.clean(dry_run=True)
 report = runtime.clean(dry_run=False, minimum_age_seconds=30 * 24 * 60 * 60)

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/getting-started.md

@@ -6,11 +6,46 @@
 python -m pip install lean-runtime
 ```
 
-On macOS and Linux, Lean Runtime installs requested Lean versions through its
+On macOS and Linux, Lean Runtime first uses a published slim check toolchain when
+one is available and otherwise installs the requested Lean version through its
 private, checksum-verified Elan installation. It does not change the user's
 default toolchain or shell profile. Windows currently requires an existing Elan
 executable through `LEAN_RUNTIME_ELAN`.
 
+## Start a Lake project
+
+Create a standard Lake library with the newest cataloged Mathlib release and
+shared exact dependencies:
+
+```bash
+lean-runtime init MyProof --mathlib
+cd MyProof
+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.
+
+Use `--mathlib 4.33.0` to select that release explicitly. Omit `--mathlib` 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.
+
+For an existing project or a directory containing many projects, preview the
+migration before applying it:
+
+```bash
+lean-runtime attach .
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+```
+
+The first two commands are read-only. Execution verifies the shared graph,
+replaces only generated package copies, and rolls back the swap if ordinary
+Lake cannot load the result. See [Local Lake projects](local-projects.md) for
+detachment, storage estimates, and the complete safety model.
+
 ## Run a file
 
 For a file inside a pinned Lake project:

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/index.md

@@ -1,7 +1,7 @@
 # Lean Runtime
 
 Lean Runtime runs Lean proofs from Python or a single `.lean` file. It discovers
-local Lake projects or compiles friendly exact dependencies into a
+local Lake projects or compiles friendly exact dependencies into an
 exact reusable environment, then returns structured results and a record of what
 was used.
 
@@ -28,9 +28,12 @@ It deliberately does not replace the official tools:
 
 The front-facing API supports setup-once Python environments, one-shot helpers,
 friendly exact package references, standalone TOML frontmatter, local-project
-discovery, exact lock output, batch checking, and asyncio. The explicit runtime
-also exposes environment libraries, portable copies, trusted publishers,
-verification, captures, policies, and storage lifecycle operations.
+discovery, shared Lake dependencies, exact lock output, batch checking, and
+asyncio. New projects can begin with a shared catalog-pinned Mathlib graph;
+existing project trees can preview and transactionally adopt the same layout.
+The explicit runtime also exposes environment libraries, portable copies,
+trusted publishers, verification, captures, policies, and storage lifecycle
+operations.
 
 The local backend executes **trusted inputs only**. Lean packages and Lake
 configuration can run native programs and arbitrary build commands; the local

lean_runtime-2.5.0/docs/local-projects.md

@@ -0,0 +1,162 @@
+# Local Lake projects
+
+Lean Runtime can discover and operate on an existing trusted Lake checkout
+without converting it into an immutable managed environment:
+
+```python
+from lean_runtime import Runtime
+
+project = Runtime().project("./my-project")
+project.build()
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+`Runtime.project()` accepts either the project root or any contained path. It
+walks upward and selects the nearest directory containing both `lean-toolchain`
+and `lakefile.toml` or `lakefile.lean`.
+
+`Runtime.check_file(path)` performs the same discovery automatically when no
+managed environment, dependency list, or explicit toolchain is supplied:
+
+```python
+result = Runtime().check_file("./my-project/MyProject/Main.lean")
+```
+
+The CLI equivalent is:
+
+```bash
+lean-runtime check-file ./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
+uniquely named disposable file under `.lake/lean-runtime/` and removes it after
+execution:
+
+```python
+result = project.check("import MyProject\nexample : True := by trivial")
+```
+
+## Reusing dependencies across projects
+
+Ordinary Lake workspaces put remote dependencies and their build artifacts in
+each repository's `.lake/packages`. New projects can start in shared mode:
+
+```bash
+lean-runtime init MyProof --mathlib
+cd MyProof
+lean-runtime build .
+```
+
+The generated files are a standard Lake project plus a small
+`lean-runtime.toml`. Root build outputs stay local; exact dependencies are
+shared. Select a cataloged release with `--mathlib 4.33.0`, or omit `--mathlib`
+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.
+
+For one existing project, preview before changing anything:
+
+```bash
+lean-runtime attach .
+lean-runtime attach . --execute
+```
+
+For a directory containing many projects:
+
+```bash
+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 project itself remains portable. To return to independent package copies:
+
+```bash
+lean-runtime detach .
+lean-runtime detach . --execute
+```
+
+Detachment copy-on-write clones the exact packages where the filesystem allows,
+probes the standalone graph, and only then removes the attachment metadata. The
+preview reports the maximum independent-copy size and available disk space;
+execution refuses to rely on copy-on-write support when there is not enough
+space for a full fallback copy.
+
+The lower-level opt-in remains available without changing project layout:
+
+```bash
+lean-runtime build . --shared
+```
+
+Or from Python:
+
+```python
+Runtime().project(".").build(shared=True)
+```
+
+Lean Runtime reads the existing `lake-manifest.json` and passes Lake a generated
+`--packages` override. Each remote package is keyed by its exact revision,
+effective transitive dependency closure, Lean toolchain, and host platform;
+local-path dependency contents are part of the surrounding workspace identity.
+Dependency sources and their `.lake/build` artifacts live under the runtime
+store, while the root project's own `.lake/build` remains in the checkout. This
+lets two different root manifests share the same Mathlib package safely. Builds
+that touch any of the same package keys are serialized because Lake may update
+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
+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.
+
+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
+downloads. Local `path` dependencies remain at their declared locations and are
+included in the workspace identity. Attached projects automatically use shared
+mode when run through `lean-runtime build`; `--local` is an explicit escape
+hatch for unattached checkouts. An attached project must be detached before a
+local build, so `--local` cannot silently continue using shared links. After
+changing the manifest or a local path dependency, rerun `lean-runtime attach .
+--execute` to refresh the ordinary-Lake links.
+
+This differs from `lake env lean File.lean`: that command only constructs the
+current workspace's environment and checks one file; it neither builds missing
+imports nor shares dependencies with another checkout. The shared build still
+uses Lake's real build graph and project targets—it only changes where locked
+dependencies come from. Attached links also let ordinary `lake build` and the
+editor load the graph; prefer `lean-runtime build` when several projects may
+build concurrently, because it serializes writes to shared artifacts.
+
+## Mutable-project provenance
+
+A local project is intentionally represented by `ProjectEnvironment`, not the
+content-addressed `Environment` used for locked dependency graphs. Its results
+therefore have `environment_id=None` and include project provenance containing:
+
+- the canonical project root;
+- a content digest excluding `.git` and `.lake`;
+- Lake configuration and manifest digests;
+- the Git revision and dirty state when Git metadata is available.
+
+The workspace digest changes when local source or configuration changes, while
+generated Lake artifacts do not affect it.
+
+Lean Runtime does not run `lake update` or rewrite the manifest.
+`project.build()` explicitly runs the pinned toolchain's `lake build`; checks
+otherwise use the project exactly as it exists. Shared builds copy or fetch only
+locked dependencies into the runtime store and leave the mutable root checkout
+in place.
+As with managed environments, Lake configuration and dependencies are trusted
+code and the local backend is not a sandbox.

{lean_runtime-2.3.0 → lean_runtime-2.5.0}/docs/portable-copies.md

@@ -25,6 +25,13 @@ and testing; normal use should keep the probe enabled.
 Saving, opening, and downloading are disk-backed and streamed. Peak memory does
 not scale with the size of the environment.
 
+`save-copy` deliberately preserves the legacy full environment, including
+sources, for users who need a self-contained development handoff. `project
+export` instead writes a source-free sparse check capsule containing only the
+selected public module's transitive closure. `open-copy` detects and verifies
+both formats. Native compilation and project development require the full
+format; proof checking should prefer the capsule.
+
 ## Environment libraries
 
 By default, Lean Runtime checks the public
@@ -64,8 +71,9 @@ lean-runtime \
   download environment.lock.json
 ```
 
-Downloaded files are retained under the runtime home. Opening another
-environment with identical dependencies reuses them without another download.
+Downloaded pack frames are verified into a raw module CAS under the runtime
+home. Opening another environment with identical module bytes reuses them even
+when its lock or top-level package differs.
 
 Old blobs can be included in garbage collection explicitly:
 
@@ -75,10 +83,11 @@ lean-runtime clean --include-downloads
 lean-runtime clean --include-downloads --execute
 ```
 
-Files used by a ready environment or an active download are retained. Cleanup
-rechecks both conditions before removing anything.
+Full OCI blobs referenced by ready legacy environments are retained. Sparse CAS
+artifacts may be reclaimed because ready projections hold their own hardlink or
+copy; active projection leases and per-artifact locks prevent races.
 
-### Required publisher publisher_verification
+### Required publisher verification
 
 For high-trust workflows, require a Sigstore signature from one exact GitHub
 Actions identity:
@@ -192,7 +201,7 @@ steps are not promised to produce byte-identical artifacts.
 
 ## Advanced storage details
 
-The gzip file is a deterministic OCI image-layout archive. It contains a
+The legacy gzip file is a deterministic OCI image-layout archive. It contains a
 standard `oci-layout`, `index.json`, one image manifest, a Lean Runtime config
 blob, and content-addressed layer blobs. The config contains the complete
 `EnvironmentLock`, build profile, environment identity, and platform
@@ -213,6 +222,13 @@ Archives use sorted paths, zero timestamps and ownership, normalized tar
 metadata, canonical JSON, and deterministic gzip headers. Exporting an unchanged
 environment twice therefore produces identical bytes and digests.
 
+A sparse capsule uses the same outer OCI layout but replaces source/package
+tarballs with seekable zstd packs and a normalized module manifest. Pack frames
+carry their own compressed digest and an inventory of raw artifact digests, so
+a ranged response is verified without downloading the surrounding pack. The
+matching check-only Lean toolchain is a separate OCI index and is never hidden
+inside the environment lock.
+
 ## Compatibility and trust
 
 `lock_id` identifies the platform-independent locked source graph.