glassvm 0.1.1__tar.gz

glassvm-0.1.1/Cargo.lock

@@ -0,0 +1,382 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "glassvm"
+version = "0.1.1"
+dependencies = [
+ "pyo3",
+ "serde_json",
+]
+
+[[package]]
+name = "glassvm_core"
+version = "0.1.1"
+dependencies = [
+ "glassvm_normalizer_contract",
+ "serde",
+ "serde_json",
+ "sha2",
+]
+
+[[package]]
+name = "glassvm_normalizer_contract"
+version = "0.1.1"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "glassvm_query"
+version = "0.1.1"
+dependencies = [
+ "glassvm_core",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "glassvm_recorder"
+version = "0.1.1"
+dependencies = [
+ "glassvm_core",
+ "serde",
+ "serde_cbor",
+ "serde_json",
+]
+
+[[package]]
+name = "glassvm_registry"
+version = "0.1.1"
+dependencies = [
+ "glassvm_core",
+]
+
+[[package]]
+name = "half"
+version = "1.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b43ede17f21864e81be2fa654110bf1e793774238d86ef8555c37e6519c0403"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab53c047fcd1a1d2a8820fe84f05d6be69e9526be40cb03b73f86b6b03e6d87d"
+dependencies = [
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b455933107de8642b4487ed26d912c2d899dec6114884214a0b3bb3be9261ea6"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c85c9cbfaddf651b1221594209aed57e9e5cff63c4d11d1feead529b872a089"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a5b10c9bf9888125d917fb4d2ca2d25c8df94c7ab5a52e13313a07e050a3b02"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "03b51720d314836e53327f5871d4c0cfb4fb37cc2c4a11cc71907a86342c40f9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_cbor"
+version = "0.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bef2ebfde456fb76bbcf9f59315333decc4fda0b2b44b420243c11e0f5ec1f5"
+dependencies = [
+ "half",
+ "serde",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

glassvm-0.1.1/Cargo.toml

@@ -0,0 +1,7 @@
+[workspace]
+members = ["python/facade"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.1"
+edition = "2024"

glassvm-0.1.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: glassvm
+Version: 0.1.1
+Requires-Dist: glassvm-chip8==0.1.1 ; extra == 'all'
+Requires-Dist: glassvm-pico8==0.1.1 ; extra == 'all'
+Requires-Dist: glassvm-tic80==0.1.1 ; extra == 'all'
+Requires-Dist: glassvm-chip8==0.1.1 ; extra == 'chip8'
+Requires-Dist: glassvm-pico8==0.1.1 ; extra == 'pico8'
+Requires-Dist: glassvm-tic80==0.1.1 ; extra == 'tic80'
+Provides-Extra: all
+Provides-Extra: chip8
+Provides-Extra: pico8
+Provides-Extra: tic80
+Summary: Generic Python facade for entry-point-discovered GlassVM machine bundles
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.12

glassvm-0.1.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["maturin[zig]>=1.0,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "glassvm"
+version = "0.1.1"
+requires-python = ">=3.12"
+description = "Generic Python facade for entry-point-discovered GlassVM machine bundles"
+license = "BSD-3-Clause"
+
+[project.optional-dependencies]
+chip8 = ["glassvm-chip8==0.1.1"]
+pico8 = ["glassvm-pico8==0.1.1"]
+tic80 = ["glassvm-tic80==0.1.1"]
+all = [
+    "glassvm-chip8==0.1.1",
+    "glassvm-pico8==0.1.1",
+    "glassvm-tic80==0.1.1",
+]
+
+[tool.maturin]
+module-name = "glassvm"
+manifest-path = "python/facade/Cargo.toml"

glassvm-0.1.1/python/facade/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "glassvm"
+version = "0.1.1"
+edition = "2024"
+license = "BSD-3-Clause"
+publish = false
+
+[lib]
+name = "glassvm"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3 = { version = "0.27", features = ["extension-module"] }
+serde_json = "1"

glassvm-0.1.1/python/facade/src/lib.rs

@@ -0,0 +1,460 @@
+//! Generic Python facade for entry-point-discovered GlassVM machine bundles.
+//!
+//! The base wheel contains no machine implementation. Bundle wheels register
+//! provider entry points in the `glassvm.machine_bundles` group and own the
+//! machine-specific preparation and execution implementation.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use pyo3::prelude::*;
+use pyo3::types::{PyBytes, PyDict};
+use serde_json::Value;
+
+const PYTHON_BUNDLE_ENTRY_POINT_GROUP: &str = "glassvm.machine_bundles";
+const PYTHON_BUNDLE_PROVIDER_CONTRACT: &str = "glassvm.python_bundle";
+const PYTHON_BUNDLE_PROTOCOL_VERSION: ProtocolVersion = ProtocolVersion {
+    major: 1,
+    minor: 0,
+    patch: 0,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct ProtocolVersion {
+    major: u16,
+    minor: u16,
+    patch: u16,
+}
+
+fn parse_protocol_version(value: &Value, entry_point: &str) -> Result<ProtocolVersion, String> {
+    let object = value.as_object().ok_or_else(|| {
+        format!(
+            "entry point {entry_point:?} provider has invalid protocol_version: expected an object"
+        )
+    })?;
+    for field in object.keys() {
+        if !matches!(field.as_str(), "major" | "minor" | "patch") {
+            return Err(format!(
+                "entry point {entry_point:?} provider has invalid protocol_version: unsupported field {field:?}"
+            ));
+        }
+    }
+    let component = |field: &str| -> Result<u16, String> {
+        let value = object.get(field).and_then(Value::as_u64).ok_or_else(|| {
+            format!(
+                "entry point {entry_point:?} provider has invalid protocol_version: {field:?} must be an unsigned integer"
+            )
+        })?;
+        u16::try_from(value).map_err(|_| {
+            format!(
+                "entry point {entry_point:?} provider has invalid protocol_version: {field:?} is out of range"
+            )
+        })
+    };
+    Ok(ProtocolVersion {
+        major: component("major")?,
+        minor: component("minor")?,
+        patch: component("patch")?,
+    })
+}
+
+fn validate_bundle_provider(
+    mut provider: Value,
+    entry_point: &str,
+) -> Result<(String, Value), String> {
+    let object = provider
+        .as_object_mut()
+        .ok_or_else(|| "bundle provider must return a JSON object".to_owned())?;
+    let protocol = object
+        .get("protocol")
+        .and_then(Value::as_str)
+        .ok_or_else(|| {
+            format!("entry point {entry_point:?} provider is missing string field \"protocol\"")
+        })?;
+    if protocol != PYTHON_BUNDLE_PROVIDER_CONTRACT {
+        return Err(format!(
+            "entry point {entry_point:?} returned unsupported provider protocol {protocol:?}"
+        ));
+    }
+    let protocol_version = object.get("protocol_version").ok_or_else(|| {
+        format!("entry point {entry_point:?} provider is missing object field \"protocol_version\"")
+    })?;
+    let protocol_version = parse_protocol_version(protocol_version, entry_point)?;
+    if protocol_version != PYTHON_BUNDLE_PROTOCOL_VERSION {
+        return Err(format!(
+            "entry point {entry_point:?} returned unsupported provider protocol version {}.{}.{}",
+            protocol_version.major, protocol_version.minor, protocol_version.patch
+        ));
+    }
+
+    const REQUIRED_STRING_FIELDS: &[&str] = &[
+        "machine_id",
+        "distribution",
+        "module",
+        "prepare_function",
+        "execute_function",
+        "bundle_version",
+    ];
+    for field in REQUIRED_STRING_FIELDS {
+        if object
+            .get(*field)
+            .and_then(Value::as_str)
+            .is_none_or(str::is_empty)
+        {
+            return Err(format!(
+                "entry point {entry_point:?} provider is missing string field {field:?}"
+            ));
+        }
+    }
+
+    for field in object.keys() {
+        if !matches!(
+            field.as_str(),
+            "protocol"
+                | "protocol_version"
+                | "machine_id"
+                | "distribution"
+                | "module"
+                | "prepare_function"
+                | "execute_function"
+                | "bundle_version"
+        ) {
+            return Err(format!(
+                "entry point {entry_point:?} provider contains unsupported metadata field {field:?}"
+            ));
+        }
+    }
+    let machine_id = object
+        .get("machine_id")
+        .and_then(Value::as_str)
+        .expect("machine_id was validated")
+        .to_owned();
+    object.insert(
+        "entry_point".to_owned(),
+        Value::String(entry_point.to_owned()),
+    );
+    Ok((machine_id, provider))
+}
+
+fn provider_string(value: &Value, field: &str) -> Result<String, String> {
+    value
+        .get(field)
+        .and_then(Value::as_str)
+        .map(str::to_owned)
+        .ok_or_else(|| format!("bundle provider field {field:?} is not a string"))
+}
+
+fn discover_bundle_values(py: Python<'_>) -> PyResult<Vec<Value>> {
+    let metadata = py.import("importlib.metadata")?;
+    let all_entries = metadata.call_method0("entry_points")?;
+    let kwargs = PyDict::new(py);
+    kwargs.set_item("group", PYTHON_BUNDLE_ENTRY_POINT_GROUP)?;
+    let entries = if all_entries.hasattr("select")? {
+        all_entries.call_method("select", (), Some(&kwargs))?
+    } else {
+        all_entries
+    };
+
+    let mut providers = Vec::new();
+    let mut machine_ids = std::collections::BTreeSet::new();
+    for item in entries.try_iter()? {
+        let entry = item?;
+        let entry_point = entry.getattr("name")?.extract::<String>()?;
+        let provider = entry.call_method0("load")?;
+        let encoded = provider.call0()?.extract::<String>()?;
+        let value: Value = serde_json::from_str(&encoded).map_err(|error| {
+            pyo3::exceptions::PyRuntimeError::new_err(format!(
+                "bundle entry point {entry_point:?} returned invalid JSON: {error}"
+            ))
+        })?;
+        let (machine_id, value) = validate_bundle_provider(value, &entry_point)
+            .map_err(pyo3::exceptions::PyRuntimeError::new_err)?;
+        if !machine_ids.insert(machine_id.clone()) {
+            return Err(pyo3::exceptions::PyRuntimeError::new_err(format!(
+                "multiple bundle entry points advertise machine_id {machine_id:?}"
+            )));
+        }
+        providers.push((machine_id, value));
+    }
+    providers.sort_by(|left, right| left.0.cmp(&right.0));
+    Ok(providers
+        .into_iter()
+        .map(|(_, provider)| provider)
+        .collect())
+}
+
+/// Discover separately installed machine-bundle wheels through Python entry
+/// points. Providers return metadata only; this boundary does not exchange
+/// Rust trait objects or invoke Python during machine execution.
+#[pyfunction]
+fn discover_bundles(py: Python<'_>) -> PyResult<String> {
+    serde_json::to_string(&discover_bundle_values(py)?).map_err(|error| {
+        pyo3::exceptions::PyRuntimeError::new_err(format!("cannot encode bundle metadata: {error}"))
+    })
+}
+
+#[derive(Debug, Clone)]
+struct PythonBundleProvider {
+    protocol: String,
+    protocol_version: ProtocolVersion,
+    entry_point: String,
+    machine_id: String,
+    distribution: String,
+    module: String,
+    prepare_function: String,
+    execute_function: String,
+    bundle_version: String,
+}
+
+fn parse_bundle_providers(values: Vec<Value>) -> Result<Vec<PythonBundleProvider>, String> {
+    values
+        .into_iter()
+        .map(|value| {
+            Ok(PythonBundleProvider {
+                protocol: provider_string(&value, "protocol")?,
+                protocol_version: parse_protocol_version(
+                    value
+                        .get("protocol_version")
+                        .ok_or_else(|| "bundle provider is missing protocol_version".to_owned())?,
+                    "parsed provider",
+                )?,
+                entry_point: provider_string(&value, "entry_point")?,
+                machine_id: provider_string(&value, "machine_id")?,
+                distribution: provider_string(&value, "distribution")?,
+                module: provider_string(&value, "module")?,
+                prepare_function: provider_string(&value, "prepare_function")?,
+                execute_function: provider_string(&value, "execute_function")?,
+                bundle_version: provider_string(&value, "bundle_version")?,
+            })
+        })
+        .collect()
+}
+
+fn json_argument(
+    py: Python<'_>,
+    value: Option<&Bound<'_, PyAny>>,
+    field: &str,
+) -> PyResult<String> {
+    let Some(value) = value else {
+        return Ok("null".to_owned());
+    };
+    py.import("json")?
+        .call_method1("dumps", (value,))?
+        .extract::<String>()
+        .map_err(|error| {
+            pyo3::exceptions::PyValueError::new_err(format!(
+                "{field} must be JSON-compatible: {error}"
+            ))
+        })
+}
+
+#[pyclass]
+struct Runtime {
+    providers: Vec<PythonBundleProvider>,
+}
+
+#[pyclass]
+struct PreparedRun {
+    provider: PythonBundleProvider,
+    /// Provider-owned preparation state. This is deliberately an in-process
+    /// Python object, not a serialization, persistence, or replay format.
+    prepared: Py<PyAny>,
+}
+
+static NEXT_PYTHON_RUN_ID: AtomicU64 = AtomicU64::new(1);
+
+#[pymethods]
+impl Runtime {
+    #[staticmethod]
+    fn discover(py: Python<'_>) -> PyResult<Self> {
+        let providers = parse_bundle_providers(discover_bundle_values(py)?).map_err(|error| {
+            pyo3::exceptions::PyRuntimeError::new_err(format!("invalid bundle provider: {error}"))
+        })?;
+        Ok(Self { providers })
+    }
+
+    fn bundles(&self) -> PyResult<String> {
+        let values = self
+            .providers
+            .iter()
+            .map(|provider| {
+                serde_json::json!({
+                    "protocol": provider.protocol,
+                    "protocol_version": {
+                        "major": provider.protocol_version.major,
+                        "minor": provider.protocol_version.minor,
+                        "patch": provider.protocol_version.patch,
+                    },
+                    "entry_point": provider.entry_point,
+                    "machine_id": provider.machine_id,
+                    "distribution": provider.distribution,
+                    "module": provider.module,
+                    "prepare_function": provider.prepare_function,
+                    "execute_function": provider.execute_function,
+                    "bundle_version": provider.bundle_version,
+                })
+            })
+            .collect::<Vec<_>>();
+        serde_json::to_string(&values)
+            .map_err(|error| pyo3::exceptions::PyRuntimeError::new_err(error.to_string()))
+    }
+
+    #[pyo3(signature = (machine_id, artifact, configuration = None, input_schedule = None, execution_controls = None, observation = None))]
+    fn prepare(
+        &self,
+        py: Python<'_>,
+        machine_id: &str,
+        artifact: &[u8],
+        configuration: Option<&Bound<'_, PyAny>>,
+        input_schedule: Option<&Bound<'_, PyAny>>,
+        execution_controls: Option<&Bound<'_, PyAny>>,
+        observation: Option<&Bound<'_, PyAny>>,
+    ) -> PyResult<PreparedRun> {
+        let provider = self
+            .providers
+            .iter()
+            .find(|provider| provider.machine_id == machine_id)
+            .cloned()
+            .ok_or_else(|| {
+                pyo3::exceptions::PyLookupError::new_err(format!(
+                    "machine bundle {machine_id:?} is not installed; install with `uv add \"glassvm[{machine_id}]\"`"
+                ))
+            })?;
+        let module = py.import(&provider.module)?;
+        let prepare = module.getattr(&provider.prepare_function)?;
+        let run_id = format!(
+            "python-{}-{}",
+            provider.machine_id,
+            NEXT_PYTHON_RUN_ID.fetch_add(1, Ordering::Relaxed)
+        );
+        let prepared = prepare.call1((
+            PyBytes::new(py, artifact),
+            run_id,
+            json_argument(py, configuration, "configuration")?,
+            json_argument(py, input_schedule, "input_schedule")?,
+            json_argument(py, execution_controls, "execution_controls")?,
+            json_argument(py, observation, "observation")?,
+        ))?;
+        Ok(PreparedRun {
+            provider,
+            prepared: prepared.unbind(),
+        })
+    }
+}
+
+#[pymethods]
+impl PreparedRun {
+    #[pyo3(signature = (output_path))]
+    fn execute(&self, py: Python<'_>, output_path: &str) -> PyResult<Py<PyAny>> {
+        let module = py.import(&self.provider.module)?;
+        let execute = module.getattr(&self.provider.execute_function)?;
+        let result = execute.call1((self.prepared.bind(py), output_path))?;
+        if !result.is_instance_of::<PyDict>() {
+            return Err(pyo3::exceptions::PyTypeError::new_err(
+                "bundle execute_prepared must return a structured mapping",
+            ));
+        }
+        Ok(result.unbind())
+    }
+}
+
+#[pymodule]
+fn glassvm(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<Runtime>()?;
+    m.add_class::<PreparedRun>()?;
+    m.add_function(wrap_pyfunction!(discover_bundles, m)?)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::{
+        PYTHON_BUNDLE_PROTOCOL_VERSION, PYTHON_BUNDLE_PROVIDER_CONTRACT, parse_bundle_providers,
+        validate_bundle_provider,
+    };
+
+    #[test]
+    fn canonical_provider_requires_both_canonical_operations() {
+        let (_, provider) = validate_bundle_provider(
+            json!({
+                "protocol": "glassvm.python_bundle",
+                "protocol_version": {"major": 1, "minor": 0, "patch": 0},
+                "machine_id": "chip8",
+                "distribution": "glassvm-chip8",
+                "module": "glassvm_chip8",
+                "prepare_function": "prepare_run",
+                "execute_function": "execute_prepared",
+                "bundle_version": "0.1.0"
+            }),
+            "chip8",
+        )
+        .expect("valid canonical provider");
+        let parsed = parse_bundle_providers(vec![provider]).expect("parse provider");
+        assert_eq!(parsed[0].protocol, PYTHON_BUNDLE_PROVIDER_CONTRACT);
+        assert_eq!(parsed[0].protocol_version, PYTHON_BUNDLE_PROTOCOL_VERSION);
+        assert_eq!(parsed[0].prepare_function, "prepare_run");
+        assert_eq!(parsed[0].execute_function, "execute_prepared");
+    }
+
+    #[test]
+    fn zero_providers_is_valid() {
+        assert!(parse_bundle_providers(Vec::new()).unwrap().is_empty());
+    }
+
+    #[test]
+    fn wrong_protocol_version_is_rejected() {
+        let error = validate_bundle_provider(
+            json!({
+                "protocol": "glassvm.python_bundle",
+                "protocol_version": {"major": 2, "minor": 0, "patch": 0},
+                "machine_id": "chip8",
+                "distribution": "glassvm-chip8",
+                "module": "glassvm_chip8",
+                "prepare_function": "prepare_run",
+                "execute_function": "execute_prepared",
+                "bundle_version": "0.1.0"
+            }),
+            "chip8",
+        )
+        .expect_err("unsupported protocol version must fail closed");
+        assert!(error.contains("unsupported provider protocol version"));
+    }
+
+    #[test]
+    fn legacy_protocol_name_is_rejected_without_fallback() {
+        let error = validate_bundle_provider(
+            json!({
+                "protocol": format!("{PYTHON_BUNDLE_PROVIDER_CONTRACT}.v1"),
+                "protocol_version": {"major": 1, "minor": 0, "patch": 0},
+                "machine_id": "chip8",
+                "distribution": "glassvm-chip8",
+                "module": "glassvm_chip8",
+                "prepare_function": "prepare_run",
+                "execute_function": "execute_prepared",
+                "bundle_version": "0.1.0"
+            }),
+            "chip8",
+        )
+        .expect_err("legacy protocol names must not dispatch");
+        assert!(error.contains("unsupported provider protocol"));
+    }
+
+    #[test]
+    fn canonical_provider_rejects_missing_execute_operation() {
+        let error = validate_bundle_provider(
+            json!({
+                "protocol": "glassvm.python_bundle",
+                "protocol_version": {"major": 1, "minor": 0, "patch": 0},
+                "machine_id": "chip8",
+                "distribution": "glassvm-chip8",
+                "module": "glassvm_chip8",
+                "prepare_function": "prepare_run",
+                "bundle_version": "0.1.0"
+            }),
+            "chip8",
+        )
+        .expect_err("missing execute operation must fail");
+        assert!(error.contains("execute_function"));
+    }
+}

glassvm-0.1.1/python/facade/tests/test_provider_lifecycle.py

@@ -0,0 +1,34 @@
+"""Base-wheel smoke coverage for the generic GlassVM provider facade."""
+
+import json
+import unittest
+
+import glassvm
+
+class ProviderDiscoveryTests(unittest.TestCase):
+    def setUp(self):
+        self.runtime = glassvm.Runtime.discover()
+
+    def test_base_runtime_discovers_entry_points_without_static_bundle_assumptions(self):
+        metadata = json.loads(self.runtime.bundles())
+        self.assertIsInstance(metadata, list)
+        machine_ids = [entry["machine_id"] for entry in metadata]
+        self.assertEqual(machine_ids, sorted(machine_ids))
+
+        for entry in metadata:
+            with self.subTest(machine_id=entry["machine_id"]):
+                self.assertEqual(entry["protocol"], "glassvm.python_bundle")
+                self.assertEqual(
+                    entry["protocol_version"],
+                    {"major": 1, "minor": 0, "patch": 0},
+                )
+                self.assertEqual(entry["prepare_function"], "prepare_run")
+                self.assertEqual(entry["execute_function"], "execute_prepared")
+
+    def test_unavailable_machine_fails_at_the_facade_boundary(self):
+        with self.assertRaises(LookupError):
+            self.runtime.prepare("glassvm.machine.not-installed", b"")
+
+
+if __name__ == "__main__":
+    unittest.main()