lean-runtime 2.0.7__tar.gz → 2.0.8__tar.gz

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 2.0.8 - 2026-08-10
+
+- Add immutable, content-addressed provenance to ready-to-run program
+  descriptions and accept it through `program-create --provenance-file`.
+- Preserve the identity and import compatibility of existing version 1 program
+  descriptions while emitting version 2 descriptions for newly created programs.
+
 ## 2.0.7
 
 - Retry an OCI layer once from a clean partial after size or SHA-256 integrity

{lean_runtime-2.0.7/lean_runtime.egg-info → lean_runtime-2.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.0.7
+Version: 2.0.8
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/docs/ready-programs.md

@@ -17,6 +17,7 @@ program = runtime.create_program(
     "build/program",
     command=["my-program"],
     source_revision="0123456789abcdef0123456789abcdef01234567",
+    provenance={"example.protocol.version": "1.0.0"},
 )
 
 with program.spawn_interactive() as session:
@@ -28,8 +29,11 @@ alive and returns one decoded response per request. This is the fast path for
 large batches: prepare and verify the checker once, then stream compact inputs
 instead of elaborating a new Lean source file for every item.
 
-`create_program` records the program's files and computer compatibility. Opening
-it later with `runtime.program(program.id)` verifies that neither has changed.
+`create_program` records the program's files, computer compatibility, and
+optional flat string provenance. All three contribute to the program ID.
+Opening it later with `runtime.program(program.id)` verifies that none has
+changed. The CLI accepts the same metadata as a JSON object through
+`program-create --provenance-file`.
 
 ## Move it or share it
 

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/lean_runtime/cli.py

@@ -181,6 +181,11 @@ def parser() -> argparse.ArgumentParser:
     program_create.add_argument("--exact-environment-id")
     program_create.add_argument("--toolchain", default="unknown")
     program_create.add_argument("--capability-id")
+    program_create.add_argument(
+        "--provenance-file",
+        type=Path,
+        help="JSON object of content-addressed program provenance",
+    )
 
     program_export = commands.add_parser(
         "program-save-copy", help="save a portable copy of a ready-to-run program"
@@ -398,6 +403,14 @@ def main(argv: list[str] | None = None) -> int:
             _json(environment.inspect().to_dict())
             return 0
         if args.command == "program-create":
+            provenance = None
+            if args.provenance_file is not None:
+                value = json.loads(args.provenance_file.read_text(encoding="utf-8"))
+                if not isinstance(value, dict) or not all(
+                    isinstance(key, str) and isinstance(item, str) for key, item in value.items()
+                ):
+                    raise ValueError("program provenance file must contain a JSON string object")
+                provenance = value
             program = runtime.create_program(
                 args.payload,
                 command=args.program_command,
@@ -406,6 +419,7 @@ def main(argv: list[str] | None = None) -> int:
                 exact_environment_id=args.exact_environment_id,
                 toolchain=args.toolchain,
                 capability_id=args.capability_id,
+                provenance=provenance,
             )
             _json(
                 {

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/lean_runtime/programs.py

@@ -14,9 +14,10 @@ import tempfile
 import uuid
 from collections.abc import Mapping, Sequence
 from contextlib import suppress
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
+from types import MappingProxyType
 from typing import Any, cast
 
 from ._paths import remove_tree
@@ -47,8 +48,10 @@ from .policies import ExecutionPolicy
 from .serialization import canonical_json_bytes, sha256_id, write_json_atomic
 from .store import EnvironmentStore, clone_tree, platform_compatibility, platform_record
 
-PROGRAM_SCHEMA = "lean-runtime-execution-program/1"
-PROGRAM_CONFIG_MEDIA_TYPE = "application/vnd.lean-runtime.program.config.v1+json"
+LEGACY_PROGRAM_SCHEMA = "lean-runtime-execution-program/1"
+PROGRAM_SCHEMA = "lean-runtime-execution-program/2"
+LEGACY_PROGRAM_CONFIG_MEDIA_TYPE = "application/vnd.lean-runtime.program.config.v1+json"
+PROGRAM_CONFIG_MEDIA_TYPE = "application/vnd.lean-runtime.program.config.v2+json"
 PROGRAM_LAYER_MEDIA_TYPE = "application/vnd.lean-runtime.program.layer.v1.tar+gzip"
 _PROGRAM_ID = re.compile(r"program_[0-9a-f]{64}")
 
@@ -106,11 +109,14 @@ class ProgramDescription:
     exact_environment_id: str | None = None
     toolchain: str = "unknown"
     capability_id: str | None = None
+    provenance: Mapping[str, str] = field(default_factory=dict)
     schema: str = PROGRAM_SCHEMA
 
     def __post_init__(self) -> None:
-        if self.schema != PROGRAM_SCHEMA:
+        if self.schema not in {LEGACY_PROGRAM_SCHEMA, PROGRAM_SCHEMA}:
             raise EnvironmentError(f"unsupported program schema: {self.schema!r}")
+        if self.schema == LEGACY_PROGRAM_SCHEMA and self.provenance:
+            raise EnvironmentError("legacy program descriptions cannot contain provenance")
         if not self.command or any(not isinstance(part, str) or not part for part in self.command):
             raise EnvironmentError("program command must contain non-empty strings")
         _relative_executable(self.command[0])
@@ -118,13 +124,26 @@ class ProgramDescription:
             raise EnvironmentError("program command executable is absent from its file inventory")
         if not re.fullmatch(r"[0-9a-f]{40,64}", self.source_revision):
             raise EnvironmentError("program source revision must be an exact Git commit")
+        if not all(
+            isinstance(key, str)
+            and bool(re.fullmatch(r"[a-z0-9][a-z0-9._-]*", key))
+            and isinstance(value, str)
+            and bool(value)
+            for key, value in self.provenance.items()
+        ):
+            raise EnvironmentError(
+                "program provenance must contain non-empty string values under canonical keys"
+            )
+        object.__setattr__(
+            self, "provenance", MappingProxyType(dict(sorted(self.provenance.items())))
+        )
 
     @property
     def program_id(self) -> str:
         return sha256_id("program", self.to_dict(include_id=False))
 
     def to_dict(self, *, include_id: bool = True) -> dict[str, Any]:
-        value = {
+        value: dict[str, Any] = {
             "schema": self.schema,
             "command": list(self.command),
             "files": dict(sorted(self.files.items())),
@@ -135,6 +154,8 @@ class ProgramDescription:
             "toolchain": self.toolchain,
             "capability_id": self.capability_id,
         }
+        if self.schema == PROGRAM_SCHEMA:
+            value["provenance"] = dict(sorted(self.provenance.items()))
         return {"program_id": self.program_id, **value} if include_id else value
 
     @classmethod
@@ -150,6 +171,10 @@ class ProgramDescription:
             raise EnvironmentError("program manifest file inventory is invalid")
         if not isinstance(compatibility, dict):
             raise EnvironmentError("program platform compatibility is invalid")
+        schema = str(value.get("schema", ""))
+        provenance = value.get("provenance", {})
+        if not isinstance(provenance, dict):
+            raise EnvironmentError("program provenance is invalid")
         manifest = cls(
             command=tuple(command),
             files={str(name): dict(record) for name, record in files.items()},
@@ -169,7 +194,8 @@ class ProgramDescription:
             capability_id=(
                 str(value["capability_id"]) if value.get("capability_id") is not None else None
             ),
-            schema=str(value.get("schema", "")),
+            provenance={str(key): item for key, item in provenance.items()},
+            schema=schema,
         )
         recorded = value.get("program_id")
         if recorded is not None and recorded != manifest.program_id:
@@ -323,6 +349,7 @@ class ProgramManager:
         exact_environment_id: str | None = None,
         toolchain: str = "unknown",
         capability_id: str | None = None,
+        provenance: Mapping[str, str] | None = None,
     ) -> ReadyProgram:
         payload = payload.expanduser().resolve()
         if not payload.is_dir():
@@ -336,6 +363,7 @@ class ProgramManager:
             exact_environment_id=exact_environment_id,
             toolchain=toolchain,
             capability_id=capability_id,
+            provenance=dict(provenance or {}),
         )
         destination = self.store.programs / manifest.program_id
         with FileLock(self.store.lock_dir / f"{manifest.program_id}.lock", timeout=1800):
@@ -392,7 +420,12 @@ class ProgramManager:
                 )
                 config_path = staging / "config.json"
                 config_path.write_bytes(canonical_json_bytes(program.description.to_dict()))
-                config = _blob_descriptor_path(config_path, PROGRAM_CONFIG_MEDIA_TYPE)
+                config_media_type = (
+                    LEGACY_PROGRAM_CONFIG_MEDIA_TYPE
+                    if program.description.schema == LEGACY_PROGRAM_SCHEMA
+                    else PROGRAM_CONFIG_MEDIA_TYPE
+                )
+                config = _blob_descriptor_path(config_path, config_media_type)
                 manifest_path = staging / "manifest.json"
                 manifest_path.write_bytes(
                     canonical_json_bytes(
@@ -507,7 +540,11 @@ class ProgramManager:
             or len(layers) != 1
         ):
             raise EnvironmentError("program OCI manifest is incomplete")
-        _require_media_type(config_descriptor, PROGRAM_CONFIG_MEDIA_TYPE, "program config")
+        if config_descriptor.get("mediaType") not in {
+            LEGACY_PROGRAM_CONFIG_MEDIA_TYPE,
+            PROGRAM_CONFIG_MEDIA_TYPE,
+        }:
+            raise EnvironmentError("program config has an unsupported media type")
         _require_media_type(layers[0], PROGRAM_LAYER_MEDIA_TYPE, "program layer")
         config_path = _descriptor_blob_path(entries, config_descriptor, "program config")
         manifest = ProgramDescription.from_dict(

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/lean_runtime/runtime.py

@@ -219,6 +219,7 @@ class Runtime:
         exact_environment_id: str | None = None,
         toolchain: str = "unknown",
         capability_id: str | None = None,
+        provenance: Mapping[str, str] | None = None,
     ) -> ReadyProgram:
         """Create a verified ready-to-run program from a payload directory."""
         return self.programs.create(
@@ -229,6 +230,7 @@ class Runtime:
             exact_environment_id=exact_environment_id,
             toolchain=toolchain,
             capability_id=capability_id,
+            provenance=provenance,
         )
 
     def program(self, program_id: str) -> ReadyProgram:

{lean_runtime-2.0.7 → lean_runtime-2.0.8/lean_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.0.7
+Version: 2.0.8
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lean-runtime"
-version = "2.0.7"
+version = "2.0.8"
 description = "Run Lean 4 proofs from Python or standalone files"
 readme = "README.md"
 requires-python = ">=3.10"

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/tests/test_cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from types import SimpleNamespace
 
 from lean_runtime.bundles import PortableCopyInfo
 from lean_runtime.cli import _print_operation_failure, main, parser
@@ -172,6 +173,44 @@ def test_save_copy_cli_reports_copy_identity(monkeypatch, tmp_path: Path, capsys
     assert json.loads(capsys.readouterr().out)["copy_id"] == info.copy_id
 
 
+def test_program_create_cli_loads_content_addressed_provenance(
+    monkeypatch, tmp_path: Path, capsys
+) -> None:
+    payload = tmp_path / "payload"
+    payload.mkdir()
+    profile = tmp_path / "profile.json"
+    profile.write_text(json.dumps({"example.protocol.version": "1.0.0"}))
+    observed = {}
+
+    def create_program(_runtime, selected_payload, **options):
+        observed.update(payload=selected_payload, **options)
+        return SimpleNamespace(
+            id="program_" + "a" * 64,
+            description=SimpleNamespace(to_dict=lambda: {"schema": "test"}),
+            root=payload,
+        )
+
+    monkeypatch.setattr("lean_runtime.cli.Runtime.create_program", create_program)
+    assert (
+        main(
+            [
+                "--quiet",
+                "program-create",
+                str(payload),
+                "--command",
+                "bin/checker",
+                "--source-revision",
+                "b" * 40,
+                "--provenance-file",
+                str(profile),
+            ]
+        )
+        == 0
+    )
+    assert observed["provenance"] == {"example.protocol.version": "1.0.0"}
+    assert json.loads(capsys.readouterr().out)["program_id"].startswith("program_")
+
+
 def test_finalize_publication_reads_computer_records(monkeypatch, tmp_path: Path, capsys) -> None:
     result = tmp_path / "computer.json"
     record = {"digest": "sha256:" + "a" * 64, "size": 42}

{lean_runtime-2.0.7 → lean_runtime-2.0.8}/tests/test_programs.py

@@ -7,6 +7,7 @@ from pathlib import Path
 import pytest
 
 from lean_runtime import EnvironmentError, ExecutionPolicy, Runtime
+from lean_runtime.programs import LEGACY_PROGRAM_SCHEMA, ProgramDescription
 
 
 def _revision() -> str:
@@ -30,6 +31,10 @@ def test_program_identity_payload_validation_and_interactive_execution(tmp_path:
         source_revision=_revision(),
         toolchain="leanprover/lean4:v4.32.2",
         capability_id="sha256:" + hashlib.sha256(b"capabilities").hexdigest(),
+        provenance={
+            "lean.toolchain": "leanprover/lean4:v4.32.2",
+            "leancert.core.revision": "b" * 40,
+        },
     )
 
     assert program.id.startswith("program_")
@@ -40,6 +45,40 @@ def test_program_identity_payload_validation_and_interactive_execution(tmp_path:
 
     reopened = runtime.program(program.id)
     assert reopened.description.source_revision == _revision()
+    assert reopened.description.provenance["leancert.core.revision"] == "b" * 40
+
+
+def test_program_provenance_is_content_addressed(tmp_path: Path) -> None:
+    runtime = Runtime(home=tmp_path / "runtime")
+    payload = _payload(tmp_path)
+    first = runtime.create_program(
+        payload,
+        command=("echo-bridge",),
+        source_revision=_revision(),
+        provenance={"leancert.core.revision": "b" * 40},
+    )
+    second = runtime.create_program(
+        payload,
+        command=("echo-bridge",),
+        source_revision=_revision(),
+        provenance={"leancert.core.revision": "c" * 40},
+    )
+
+    assert first.id != second.id
+
+
+def test_legacy_program_identity_remains_stable() -> None:
+    description = ProgramDescription(
+        command=("echo-bridge",),
+        files={"echo-bridge": {"kind": "file", "sha256": "sha256:" + "0" * 64}},
+        computer_compatibility={"schema": "computer/1"},
+        source_revision=_revision(),
+        schema=LEGACY_PROGRAM_SCHEMA,
+    )
+
+    restored = ProgramDescription.from_dict(description.to_dict())
+    assert restored.program_id == description.program_id
+    assert "provenance" not in restored.to_dict()
 
 
 def test_program_rejects_payload_tampering(tmp_path: Path) -> None: