lean-runtime 0.6.0__tar.gz → 1.0.0__tar.gz

lean_runtime-1.0.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## 1.0.0
+
+Lean Runtime v1 establishes the concise `lean-run` and `lean.setup()` workflows while making
+exact environments independently verifiable, explainable, measurable, and portable.
+
+### Breaking changes
+
+- Remove `lean-runtime audit`, `Runtime.audit()`, `AuditReport`, and `ArtifactInventory`;
+  `verify` is the sole trust surface and `verify --rebuild` performs independent rebuild checks.
+- Close and version the seven public CLI JSON schemas. Execution payloads now include stable
+  phase timings, while `inspect` and `gc` use one canonical data shape each.
+- Remove transitional compatibility surfaces introduced before v1; callers should use the
+  top-level façade, `Runtime`, and the documented v1 result types directly.
+
+### Release capabilities
+
+- Add lazy `setup`, `check`, `check_file`, and `replay` Python façade functions.
+- Add `lean-run` with strict TOML frontmatter, automatic local-project discovery,
+  exact lock input/output, concise progress, and structured JSON output.
+- Add exact `mathlib@REVISION`, `leancert@REVISION`, and
+  `owner/repository@REVISION` package references without permitting floating aliases.
+- Add `ExecutionResult.raise_for_error()` and structured `LeanCheckError` failures.
+- Rewrite the README around the front-facing workflow and expand the standalone
+  file, CLI, Python, and routing documentation.
+- Discover pinned local Lake projects from contained Lean files and expose a
+  distinct mutable `ProjectEnvironment` API.
+- Preserve project-relative file checks and record content, configuration,
+  manifest, and Git project provenance without claiming an environment identity.
+- Add transparent OCI prebuilt-cache lookup with authenticated registry pulls,
+  disk-backed blob reuse, strict fallback policy, and explicit `pull` support.
+- Add deterministic OCI publishing through `build-and-push`, with blobs and the
+  platform manifest committed before the lock-level index tag.
+- Stream bundle layers and OCI archives through temporary files instead of
+  materializing multi-gigabyte package layers in memory.
+- Add deterministic OCI image-layout export and verified, atomic environment import.
+- Verify bundle digests, lock and environment identities, package Git trees,
+  archive paths, host compatibility, and a Lean probe before publication.
+- Separate artifact compatibility identity from informational host metadata and
+  bump the environment store identity schema.
+- Add verification, decision explanations, semantic context diffs, repeated profiles, and
+  bounded matrix execution over ordinary execution results.
+- Add interruptible toolchain installation, Lake resolution, environment builds, matrix checks,
+  and project checks with process-group cleanup on cancellation and Ctrl-C.
+- Ship the public JSON schemas in wheel and source distributions and expose `schema_path()`.
+- Add reproducible case-study fixtures, clean-wheel smoke testing, and installed-wheel Lean
+  acceptance in CI.
+
+## 0.6.0
+
+- Discover packages declared with either `lakefile.toml` or `lakefile.lean`.
+- Translate Lake DSL configurations through the package's exact declared Lean
+  toolchain instead of parsing Lean source or guessing package metadata.
+
+## 0.5.0
+
+- Add `Environment.execute()` for generic commands such as `lake exe`.
+- Add managed `InteractiveSession` processes with live UTF-8 standard-I/O pipes.
+- Run interactive tools in disposable environment clones with exact provenance.
+- Enforce local timeout, memory, CPU, and bounded-transcript policies for sessions.
+- Gracefully close sessions with stdin EOF before process-group termination.
+- Persist final interactive `ExecutionResult` records and clean up instances.
+
+## 0.4.0
+
+- Add `github:owner/repository@tag-or-commit` package references.
+- Discover package identity, root module, and Lean toolchain from Lake projects.
+- Pin convenience references to exact commits before environment resolution.
+- Add one-shot `lean-runtime check FILE --with REFERENCE` execution.
+- Add `Runtime.spec_from_references()`, `resolve_references()`,
+  `ensure_references()`, and `Runtime.check(..., packages=[...])`.
+- Detect incompatible discovered toolchains across multi-package requests.
+- Avoid Elan's implicit toolchain installation during installation checks.
+
+## 0.3.0
+
+- Add safe multi-file checking and replayable multi-file captures.
+- Add cancellable native asyncio helpers.
+- Add structured lifecycle progress events.
+- Resolve friendly Git tags into exact commit locks.
+- Add installation health, cache status, environment listing, and richer inspection.
+- Add a scheduled real-ecosystem compatibility profile.
+- Store compact, content-verified one-commit source snapshots.
+- Treat direct and transitive package toolchain files as compatibility signals,
+  while making the actual selected-toolchain build authoritative.
+- Use execution leases so batch checks can clone concurrently without racing GC.
+- Build imported locked-package roots on demand inside execution workspaces.
+- Add release automation for PyPI trusted publishing.
+- Build and deploy the documentation site through GitHub Pages.
+
+## 0.2.0
+
+- Introduce content-addressed environments, exact Git locks, offline reopening,
+  execution provenance, captures, aliases, garbage collection, and trusted local
+  resource policies.

{lean_runtime-0.6.0 → lean_runtime-1.0.0}/MANIFEST.in

@@ -4,4 +4,5 @@ recursive-include docs *.md
 recursive-include examples *.toml
 recursive-include compatibility *.json *.md *.toml
 recursive-include scripts *.py
+recursive-include schemas *.json
 recursive-include tests *.py

lean_runtime-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: lean-runtime
+Version: 1.0.0
+Summary: Run Lean 4 proofs from Python or standalone files
+Author: Alejandro Radisic
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/alerad/lean-runtime
+Project-URL: Documentation, https://alerad.github.io/lean-runtime/
+Project-URL: Repository, https://github.com/alerad/lean-runtime.git
+Project-URL: Issues, https://github.com/alerad/lean-runtime/issues
+Project-URL: Changelog, https://github.com/alerad/lean-runtime/blob/main/CHANGELOG.md
+Keywords: lean4,theorem-prover,formal-verification,toolchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: tomli>=2; extra == "dev"
+Requires-Dist: jsonschema>=4.23; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# Lean Runtime
+
+Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
+Lake project or rebuilding the same dependencies on every machine.
+
+Lean Runtime discovers or resolves the environment, checks a global OCI cache,
+and returns structured Lean results with exact provenance.
+
+> **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
+> it is an orchestration boundary, not a security sandbox.
+
+## Install
+
+```bash
+python -m pip install lean-runtime
+```
+
+Lean Runtime manages its own Elan installation on macOS and Linux. Windows
+currently requires `LEAN_RUNTIME_ELAN`.
+
+## Run one Lean file
+
+Inside an existing pinned Lake project, just pass the file:
+
+```bash
+lean-run MyProject/Main.lean
+```
+
+For a portable standalone file, declare exact dependencies in TOML frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.32.2"]
+-- ///
+
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```bash
+lean-run Main.lean
+```
+
+The same context can be supplied from the command line:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2
+```
+
+Create an exact lock for CI without changing the file:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2 \
+  --lock-out environment.lock.json
+lean-run Main.lean --lock environment.lock.json
+```
+
+## Python
+
+Configure an environment once, then use it repeatedly:
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(["mathlib@v4.32.2"])
+
+result = env.check(
+    """
+    import Mathlib
+    example : 2 + 2 = 4 := by norm_num
+    """
+)
+result.raise_for_error()
+```
+
+Batch and asyncio APIs reuse that prepared environment:
+
+```python
+results = env.check_many(generated_proofs, concurrency=8)
+results = await env.check_many_async(generated_proofs, concurrency=20)
+```
+
+Local projects use the same setup pattern while retaining mutable-project
+semantics:
+
+```python
+project = lean.setup(project="./my-project")
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+One-shot helpers are available when setup reuse is unnecessary:
+
+```python
+result = lean.check(source, deps=["mathlib@v4.32.2"])
+result = lean.check_file("./my-project/MyProject/Main.lean")
+```
+
+When you need evidence rather than extra setup, the operations CLI can verify, explain,
+compare, and measure the same exact contexts:
+
+```bash
+lean-runtime verify research-stack --offline
+lean-runtime diff previous.lock.json environment.lock.json
+lean-runtime profile research-stack Main.lean --repeat 5
+lean-runtime matrix compatibility.toml Main.lean
+```
+
+Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and
+`--timings` to expose preparation versus execution time. Successful ordinary checks remain
+one concise line.
+
+Friendly references remain exact: use `mathlib@VERSION`,
+`leancert@VERSION`, `owner/repository@REVISION`, or the explicit
+`github:owner/repository@REVISION` form. Bare floating package names are never
+accepted.
+
+## Under the hood
+
+The simple API is backed by exact Git commits and trees, Lake-resolved locks,
+platform-aware content-addressed environments, atomic cross-process builds,
+transparent OCI cache reuse, replayable provenance, verification, and signed
+attestations. Advanced users can access all of it through `lean_runtime.Runtime`
+and the `lean-runtime` operations CLI.
+
+## Documentation
+
+- [Getting started](https://github.com/alerad/lean-runtime/blob/main/docs/getting-started.md)
+- [Python API](https://github.com/alerad/lean-runtime/blob/main/docs/python-api.md)
+- [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
+- [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
+- [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
+- [Environment bundles and OCI caches](https://github.com/alerad/lean-runtime/blob/main/docs/bundles.md)
+- [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
+- [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
+- [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)
+
+## License
+
+Apache License 2.0.

lean_runtime-1.0.0/README.md

@@ -0,0 +1,140 @@
+# Lean Runtime
+
+Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
+Lake project or rebuilding the same dependencies on every machine.
+
+Lean Runtime discovers or resolves the environment, checks a global OCI cache,
+and returns structured Lean results with exact provenance.
+
+> **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
+> it is an orchestration boundary, not a security sandbox.
+
+## Install
+
+```bash
+python -m pip install lean-runtime
+```
+
+Lean Runtime manages its own Elan installation on macOS and Linux. Windows
+currently requires `LEAN_RUNTIME_ELAN`.
+
+## Run one Lean file
+
+Inside an existing pinned Lake project, just pass the file:
+
+```bash
+lean-run MyProject/Main.lean
+```
+
+For a portable standalone file, declare exact dependencies in TOML frontmatter:
+
+```lean
+-- /// lean-runtime
+-- requires = ["mathlib@v4.32.2"]
+-- ///
+
+import Mathlib
+
+example : 2 + 2 = 4 := by norm_num
+```
+
+```bash
+lean-run Main.lean
+```
+
+The same context can be supplied from the command line:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2
+```
+
+Create an exact lock for CI without changing the file:
+
+```bash
+lean-run Main.lean --with mathlib@v4.32.2 \
+  --lock-out environment.lock.json
+lean-run Main.lean --lock environment.lock.json
+```
+
+## Python
+
+Configure an environment once, then use it repeatedly:
+
+```python
+import lean_runtime as lean
+
+env = lean.setup(["mathlib@v4.32.2"])
+
+result = env.check(
+    """
+    import Mathlib
+    example : 2 + 2 = 4 := by norm_num
+    """
+)
+result.raise_for_error()
+```
+
+Batch and asyncio APIs reuse that prepared environment:
+
+```python
+results = env.check_many(generated_proofs, concurrency=8)
+results = await env.check_many_async(generated_proofs, concurrency=20)
+```
+
+Local projects use the same setup pattern while retaining mutable-project
+semantics:
+
+```python
+project = lean.setup(project="./my-project")
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+One-shot helpers are available when setup reuse is unnecessary:
+
+```python
+result = lean.check(source, deps=["mathlib@v4.32.2"])
+result = lean.check_file("./my-project/MyProject/Main.lean")
+```
+
+When you need evidence rather than extra setup, the operations CLI can verify, explain,
+compare, and measure the same exact contexts:
+
+```bash
+lean-runtime verify research-stack --offline
+lean-runtime diff previous.lock.json environment.lock.json
+lean-runtime profile research-stack Main.lean --repeat 5
+lean-runtime matrix compatibility.toml Main.lean
+```
+
+Use `lean-run Main.lean --explain` to inspect context routing without executing Lean, and
+`--timings` to expose preparation versus execution time. Successful ordinary checks remain
+one concise line.
+
+Friendly references remain exact: use `mathlib@VERSION`,
+`leancert@VERSION`, `owner/repository@REVISION`, or the explicit
+`github:owner/repository@REVISION` form. Bare floating package names are never
+accepted.
+
+## Under the hood
+
+The simple API is backed by exact Git commits and trees, Lake-resolved locks,
+platform-aware content-addressed environments, atomic cross-process builds,
+transparent OCI cache reuse, replayable provenance, verification, and signed
+attestations. Advanced users can access all of it through `lean_runtime.Runtime`
+and the `lean-runtime` operations CLI.
+
+## Documentation
+
+- [Getting started](https://github.com/alerad/lean-runtime/blob/main/docs/getting-started.md)
+- [Python API](https://github.com/alerad/lean-runtime/blob/main/docs/python-api.md)
+- [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
+- [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
+- [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
+- [Environment bundles and OCI caches](https://github.com/alerad/lean-runtime/blob/main/docs/bundles.md)
+- [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
+- [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
+- [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)
+
+## License
+
+Apache License 2.0.

lean_runtime-1.0.0/docs/bundles.md

@@ -0,0 +1,222 @@
+# Environment bundles
+
+Lean Runtime can move an already built environment between compatible machines
+without rebuilding its Lake packages:
+
+```bash
+lean-runtime export research-stack --output research-stack.oci.tar.gz
+lean-runtime --home /tmp/fresh import research-stack.oci.tar.gz --name research-stack
+```
+
+The equivalent Python API is:
+
+```python
+info = runtime.export_environment("research-stack", "research-stack.oci.tar.gz")
+environment = another_runtime.import_environment("research-stack.oci.tar.gz", name="research-stack")
+```
+
+Import verifies the OCI manifest and every blob digest, recomputes the lock and
+environment identities, requires an exact platform compatibility match, checks
+each package's Git commit and tree, and runs a Lean probe. Publication uses a
+staging directory and atomic rename, so a failed import is never visible as a
+ready environment. `--no-probe` exists for inspection and testing workflows;
+normal imports should keep the probe enabled.
+
+Layer construction, archive writing, import, and registry downloads are
+disk-backed and streamed. Peak memory does not scale with package-layer size.
+
+## OCI global caches
+
+By default, Lean Runtime checks the public
+`oci://ghcr.io/alerad/lean-runtime-cache` mirror. A miss or availability failure
+falls back to the existing source build, so environment specifications do not
+change. Set `LEAN_RUNTIME_CACHES=` or construct `Runtime(caches=[])` to disable
+all remote cache lookups.
+
+Configure one or more cache repositories without changing the environment
+specification or lock:
+
+```python
+runtime = Runtime(
+    caches=["oci://ghcr.io/alerad/leancert-runtime"],
+    prebuilt="auto",
+)
+environment = runtime.ensure(lock)
+```
+
+The equivalent environment variables are:
+
+```bash
+export LEAN_RUNTIME_CACHES=oci://ghcr.io/alerad/leancert-runtime
+export LEAN_RUNTIME_PREBUILT=auto
+```
+
+`auto` tries caches in order and builds from source when an artifact is absent,
+incompatible, or temporarily unavailable. `require` makes an ordinary cache
+miss an error. `never` disables remote lookup. Digest, lock, archive-safety, and
+probe failures are security failures and never silently fall back to source.
+
+Explicit prefetch uses the same verified path:
+
+```bash
+lean-runtime \
+  --cache oci://ghcr.io/alerad/leancert-runtime \
+  pull environment.lock.json
+```
+
+Registry blobs are retained content-addressed under the runtime home. Pulling a
+second environment with an identical package layer reuses it without another
+download.
+
+Old blobs can be included in garbage collection explicitly:
+
+```bash
+# Preview, then apply after reviewing the candidates.
+lean-runtime gc --include-blobs
+lean-runtime gc --include-blobs --execute
+```
+
+Blobs referenced by an imported environment or leased by an active pull are
+retained. Collection rechecks both conditions while holding the same per-blob
+lock used by downloads.
+
+### Required publisher signatures
+
+For high-trust workflows, require a Sigstore signature from one exact GitHub
+Actions identity:
+
+```python
+runtime = Runtime(
+    caches=["oci://ghcr.io/alerad/leancert-runtime"],
+    signatures="require",
+    trusted_identity=(
+        "https://github.com/alerad/leancert/.github/workflows/cache.yml@refs/heads/main"
+    ),
+    trusted_issuer="https://token.actions.githubusercontent.com",
+)
+```
+
+CLI equivalents are `--signatures require`, `--trusted-identity`, and
+`--trusted-issuer`. Verification uses an installed Cosign 2.6.2 or 3.0.4+ and
+binds the canonical lock-index digest, certificate identity, issuer, and
+transparency-log claims. Older versions are rejected because of the patched
+[Cosign verification advisory](https://github.com/sigstore/cosign/security/advisories/GHSA-whqx-f9j3-ch6m).
+
+Signature failure is an integrity failure and never triggers source fallback.
+
+## Publishing
+
+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-push environment.lock.json \
+  --push-to oci://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
+[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.
+
+Repository authors can use the bundled composite action after checking out the
+repository and generating or retaining a lock:
+
+```yaml
+permissions:
+  contents: read
+  packages: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: ./.github/actions/cache
+    with:
+      lock: environment.lock.json
+      repository: oci://ghcr.io/${{ github.repository_owner }}/leancert-runtime
+      tag: ${{ github.ref_name }}
+      registry-username: ${{ github.actor }}
+      registry-password: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For a build matrix, have each platform publish without changing the canonical
+index and retain its JSON result:
+
+```bash
+lean-runtime build-and-push environment.lock.json \
+  --push-to oci://ghcr.io/alerad/leancert-runtime \
+  --platform-only > platform-result.json
+```
+
+After collecting the result files, one final job publishes the deterministic
+multi-platform index and human aliases:
+
+```bash
+lean-runtime publish-index "$LOCK_ID" results/*.json \
+  --repository oci://ghcr.io/alerad/leancert-runtime \
+  --tag "$GITHUB_REF_NAME"
+```
+
+The finalizer rejects duplicate OS/architecture/ABI entries. Publishing the
+index only after every required platform succeeds prevents partial build
+matrices from replacing a complete cache release.
+
+`--attest` runs package-source verification and the Lean import probe, records a
+stable inventory of all Lake build outputs, and publishes that predicate as a
+keyless Cosign attestation bound to the platform manifest (or finalized index).
+It requires Cosign and an OIDC-capable publishing environment.
+
+## Auditing
+
+Verify the embedded source markers, Git commits and trees, root lock material,
+Lean probe, and build-output inventory at any time:
+
+```bash
+lean-runtime verify research-stack
+```
+
+For an independent check, reacquire and rebuild the exact lock in a temporary
+store and compare normalized artifact inventories:
+
+```bash
+lean-runtime verify research-stack --rebuild
+```
+
+`source_verified` and `probe_passed` are the trust result. `artifact_match` is a
+separate byte-reproducibility measurement: a mismatch is reported but is not
+treated as failed source/proof verification, because native toolchains and package build
+steps are not promised to produce byte-identical artifacts.
+
+## Format version 1
+
+The 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
+compatibility record.
+
+There is one layer for the synthetic root workspace and one layer for each Lake
+package. Package layers include both source and `.lake/build`, so identical
+serialized package trees are reused by the registry transport. The Lean
+toolchain is not bundled; Elan supplies the exact toolchain named by the lock.
+
+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.
+
+## Compatibility and trust
+
+`lock_id` identifies the platform-independent locked source graph.
+`environment_id` additionally includes the release build profile and the
+versioned platform compatibility record. Informational host details remain in
+metadata but do not invalidate compatible caches across OS patch releases.
+
+A bundle is trusted executable build output. Digest, lock, Git-tree, and probe
+verification detect corruption and identity substitution, but do not prove that
+the builder compiled the sources faithfully. Registry credentials authenticate
+access but are not a builder attestation; only use cache publishers you trust.

lean_runtime-1.0.0/docs/case-study-v1.md

@@ -0,0 +1,47 @@
+# V1 release case study
+
+The release case study demonstrates the public lifecycle rather than relying on private
+benchmark hooks. It uses a prepared exact Mathlib environment and the committed mixture of
+accepted proofs, elaboration failures, and malformed input.
+
+## Run the evidence harness
+
+```bash
+python scripts/run_v1_case_study.py research-stack \
+  --concurrency 1 --concurrency 4 --concurrency 8 --concurrency 20 \
+  --repeat 5 --output benchmarks/proof_batch/results.json
+```
+
+The resulting JSON records:
+
+- runtime, Python, platform, command, and fixture identity;
+- cache state before and after the workload;
+- raw wall-time samples and min/median/mean/p95/max by concurrency;
+- stable request identity and unique execution identity;
+- bundle size and export/import durations;
+- import into an empty runtime home;
+- offline verification and captured-execution replay.
+
+The harness deliberately starts from an already prepared environment. Measure cold source
+preparation separately and state whether local, Lake, and OCI caches were empty. Do not combine
+cold source builds and warm execution into one headline number.
+
+## Clean-wheel acceptance
+
+Build and exercise the artifact users actually install:
+
+```bash
+python -m build
+python scripts/smoke_wheel.py dist/lean_runtime-1.0.0-py3-none-any.whl
+```
+
+Add `--lean` to bootstrap an isolated runtime home and run a real standalone proof. The smoke
+script creates a fresh virtual environment, installs only the wheel, clears ambient Python
+package visibility, checks both console entry points, and reads a packaged v1 schema through
+`lean_runtime.schema_path()`.
+
+## Publishing results
+
+Keep the raw JSON beside any summary. Record the exact lock and environment ID, machine and
+filesystem, command line, runtime version, repetition count, and cache state. Timings from noisy
+shared CI are evidence that the workflow completes, not a performance regression gate.