polyplug 0.1.0__tar.gz

polyplug-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: polyplug
+Version: 0.1.0
+Summary: Python host library for the polyplug plugin runtime
+License: MIT
+Project-URL: Homepage, https://github.com/polyplug/polyplug
+Project-URL: Documentation, https://github.com/polyplug/polyplug#readme
+Project-URL: Repository, https://github.com/polyplug/polyplug.git
+Project-URL: Issues, https://github.com/polyplug/polyplug/issues
+Keywords: polyplug,plugin,runtime,ffi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: polyplug-abi
+Provides-Extra: native
+Requires-Dist: polyplug-loaders-native; extra == "native"
+Provides-Extra: python
+Requires-Dist: polyplug-loaders-python; extra == "python"
+Provides-Extra: lua
+Requires-Dist: polyplug-loaders-lua; extra == "lua"
+Provides-Extra: js
+Requires-Dist: polyplug-loaders-js; extra == "js"
+Provides-Extra: dotnet
+Requires-Dist: polyplug-loaders-dotnet; extra == "dotnet"
+Provides-Extra: all
+Requires-Dist: polyplug-loaders-native; extra == "all"
+Requires-Dist: polyplug-loaders-python; extra == "all"
+Requires-Dist: polyplug-loaders-lua; extra == "all"
+Requires-Dist: polyplug-loaders-js; extra == "all"
+Requires-Dist: polyplug-loaders-dotnet; extra == "all"

polyplug-0.1.0/polyplug/__init__.py

@@ -0,0 +1,26 @@
+"""polyplug — host-side Python library for polyplug app developers."""
+
+from __future__ import annotations
+
+from polyplug._native import load_native_lib as _load_native_lib
+
+_native_lib = _load_native_lib()
+
+from polyplug.runtime import Runtime
+from polyplug_abi import ReloadPhase, ReloadPhaseType
+
+__all__ = [
+    "Runtime",
+    "ReloadPhase",
+    "ReloadPhaseType",
+    "load_native_lib",
+]
+
+
+def load_native_lib():
+    """Return the loaded native library instance.
+
+    Returns:
+        ctypes.CDLL: The loaded libpolyplug instance.
+    """
+    return _native_lib

polyplug-0.1.0/polyplug/_native/__init__.py

@@ -0,0 +1,164 @@
+"""Native library loader for polyplug.
+
+This module handles loading the native libpolyplug shared library.
+
+Resolution order (an explicit POLYPLUG_LIB always wins — this is the same
+order the FFI backend in ``polyplug.runtime`` uses, so the preloaded library
+and the backend library are always the SAME file):
+  1. The POLYPLUG_LIB environment variable (absolute path to the .so/.dylib/.dll).
+  2. Locally staged platform subdirectory (e.g. _native/linux-x64/).
+  3. System library paths (LD_LIBRARY_PATH / DYLD_LIBRARY_PATH / PATH).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import ctypes
+import platform
+from typing import Optional
+
+__all__ = ["load_native_lib", "get_native_lib_name", "NativeLibLoader"]
+
+
+def get_native_lib_name() -> str:
+    """Get the native library filename for the current platform.
+
+    Returns:
+        The platform-specific library filename.
+
+    Raises:
+        RuntimeError: If the current platform is not supported.
+    """
+    if sys.platform == "linux":
+        return "libpolyplug.so"
+    elif sys.platform == "darwin":
+        return "libpolyplug.dylib"
+    elif sys.platform == "win32":
+        return "polyplug.dll"
+    else:
+        raise RuntimeError(f"Unsupported platform: {sys.platform}")
+
+
+def get_platform_identifier() -> str:
+    """Get the platform identifier for GitHub Releases downloads.
+
+    Returns:
+        Platform identifier string (e.g., 'linux-x64', 'macos-arm64').
+
+    Raises:
+        RuntimeError: If the current platform/architecture is not supported.
+    """
+    machine = platform.machine().lower()
+
+    if sys.platform == "linux":
+        if machine in ("x86_64", "amd64"):
+            return "linux-x64"
+        elif machine == "aarch64":
+            return "linux-arm64"
+        else:
+            raise RuntimeError(f"Unsupported Linux architecture: {machine}")
+    elif sys.platform == "darwin":
+        if machine == "arm64":
+            return "macos-arm64"
+        elif machine in ("x86_64", "amd64"):
+            return "macos-x64"
+        else:
+            raise RuntimeError(f"Unsupported macOS architecture: {machine}")
+    elif sys.platform == "win32":
+        if machine in ("x86_64", "amd64"):
+            return "windows-x64"
+        else:
+            raise RuntimeError(f"Unsupported Windows architecture: {machine}")
+    else:
+        raise RuntimeError(f"Unsupported platform: {sys.platform}")
+
+
+class NativeLibLoader:
+    """Manages loading of the native polyplug library.
+
+    This class attempts to load the native library from multiple locations
+    (an explicit POLYPLUG_LIB always wins):
+    1. POLYPLUG_LIB environment variable
+    2. Embedded _native/ directory
+    3. System library paths
+
+    Attributes:
+        lib: The loaded ctypes.CDLL instance, or None if not loaded.
+        load_path: The path from which the library was loaded, or None.
+    """
+
+    def __init__(self) -> None:
+        self.lib: Optional[ctypes.CDLL] = None
+        self.load_path: Optional[str] = None
+
+    def load(self) -> ctypes.CDLL:
+        """Load the native library.
+
+        Returns:
+            The loaded ctypes.CDLL instance.
+
+        Raises:
+            RuntimeError: If the library cannot be loaded from any location.
+        """
+        if self.lib is not None:
+            return self.lib
+
+        lib_name = get_native_lib_name()
+        platform_id = get_platform_identifier()
+
+        # POLYPLUG_LIB wins over the embedded copy: the FFI backend
+        # (polyplug.runtime._resolve_lib_path) honors the env var first, so
+        # preferring the embedded copy here would dlopen TWO different
+        # libpolyplug builds into one process.
+        env_path = os.environ.get("POLYPLUG_LIB")
+        if env_path and os.path.exists(env_path):
+            self.lib = ctypes.CDLL(env_path)
+            self.load_path = env_path
+            return self.lib
+
+        embedded_path = os.path.join(os.path.dirname(__file__), platform_id, lib_name)
+
+        if os.path.exists(embedded_path):
+            self.lib = ctypes.CDLL(embedded_path)
+            self.load_path = embedded_path
+            return self.lib
+
+        try:
+            self.lib = ctypes.CDLL(lib_name)
+            self.load_path = lib_name
+            return self.lib
+        except OSError:
+            pass
+
+        raise RuntimeError(
+            f"Failed to load native library '{lib_name}'. "
+            f"Tried: {embedded_path}"
+            f"{', POLYPLUG_LIB=' + env_path if env_path else ''}"
+            f", system paths. "
+            f"Ensure the library is installed or set POLYPLUG_LIB."
+        )
+
+
+_loader: Optional[NativeLibLoader] = None
+
+
+def load_native_lib() -> ctypes.CDLL:
+    """Load the native polyplug library.
+
+    This function attempts to load the native library from
+    (an explicit POLYPLUG_LIB always wins):
+    1. The POLYPLUG_LIB environment variable
+    2. The embedded _native/ directory
+    3. System library paths
+
+    Returns:
+        The loaded ctypes.CDLL instance.
+
+    Raises:
+        RuntimeError: If the library cannot be loaded from any location.
+    """
+    global _loader
+    if _loader is None:
+        _loader = NativeLibLoader()
+    return _loader.load()

polyplug-0.1.0/polyplug/runtime.py

@@ -0,0 +1,486 @@
+"""
+polyplug Python Host Library
+
+After 18-02/18-03: All operations go through HostApi struct fields.
+Only two FFI exports remain: polyplug_runtime_create, polyplug_runtime_destroy.
+
+The Runtime class holds a HostApi pointer and calls methods through struct fields.
+All FFI struct types are imported from the auto-generated polyplug_abi module.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+from typing import Callable, Optional, Protocol, runtime_checkable
+
+# Import all FFI struct types from the auto-generated abi module.
+# The polyplug_abi package re-exports from sdks/python/abi/abi.py (per D-28).
+from polyplug_abi import (
+    AbiError,
+    AbiErrorCode,
+    Array,
+    Compatibility,
+    DispatchMechanisms,
+    GuestContractHandle,
+    GuestContractInstance,
+    GuestContractInterface,
+    HostContractInterface,
+    HostContractInstance,
+    HostApi,
+    ReloadPhase,
+    ReloadPhaseType,
+    RuntimeConfig,
+)
+
+# The ABI-level ReloadPhase ctypes Structure (the on_reload callback receives a
+# const pointer to this 48-byte struct). The `polyplug_abi` package re-exports a
+# higher-level Python `ReloadPhase` wrapper class under the same name, so the
+# raw ctypes Structure is imported from its defining module to disambiguate.
+from polyplug_abi.abi import ReloadPhase as AbiReloadPhase
+
+_LIB_NAME: str = "polyplug"
+
+# ─── Compatibility Constants ─────────────────────────────────────────────────────
+# These match polyplug_abi::Compatibility #[repr(u32)] enum
+
+COMPATIBILITY_STRICT: int = Compatibility.Strict
+COMPATIBILITY_RELAXED: int = Compatibility.Relaxed
+COMPATIBILITY_YOLO: int = Compatibility.Yolo
+
+# GuestContractHandle is `#[repr(C)] { index: u32, generation: u32 }` (8 bytes, align 4).
+# The null handle sentinel has index == u32::MAX (0xFFFFFFFF) and generation == 0.
+_NULL_HANDLE_INDEX: int = (1 << 32) - 1
+
+_BACKEND: str = "ctypes"
+_cffi_available: bool = False
+
+try:
+    import cffi
+    _cffi_available = True
+    _BACKEND = "cffi"
+except ImportError:
+    pass
+
+
+# ─── Backend Protocol (18-03: HostApi-based) ─────────────────────────────────
+
+@runtime_checkable
+class Backend(Protocol):
+    """Protocol for HostApi-based FFI backend.
+
+    Only two FFI bindings needed: create and destroy.
+    All operations go through HostApi struct fields.
+    """
+
+    def create_host_interface(self, config_ptr: int = 0) -> int: ...
+    def destroy_host_interface(self, host: int) -> None: ...
+    def load_host_interface(self, host: int) -> HostApi: ...
+
+
+class CTypesBackend:
+    """ctypes-based FFI backend for HostApi operations."""
+
+    def __init__(self, lib_path: str) -> None:
+        self.ctypes = ctypes
+        self.lib: ctypes.CDLL = ctypes.CDLL(lib_path)
+        self._setup_bindings()
+
+    def _setup_bindings(self) -> None:
+        # Only two FFI exports: create (takes optional *const RuntimeConfig,
+        # null for defaults) and destroy.
+        self.lib.polyplug_runtime_create.argtypes = [self.ctypes.c_void_p]
+        self.lib.polyplug_runtime_create.restype = self.ctypes.c_void_p
+
+        self.lib.polyplug_runtime_destroy.argtypes = [self.ctypes.c_void_p]
+        self.lib.polyplug_runtime_destroy.restype = None
+
+    def create_host_interface(self, config_ptr: int = 0) -> int:
+        """Create runtime and return HostApi pointer.
+
+        Args:
+            config_ptr: Address of a RuntimeConfig struct, or 0 for defaults.
+        """
+        return self.lib.polyplug_runtime_create(config_ptr or None) or 0
+
+    def destroy_host_interface(self, host: int) -> None:
+        """Destroy HostApi and runtime."""
+        self.lib.polyplug_runtime_destroy(host)
+
+    def load_host_interface(self, host: int) -> HostApi:
+        """Load HostApi struct from pointer."""
+        return HostApi.from_address(host)
+
+
+class CFFIBackend:
+    """cffi ABI mode backend for HostApi operations."""
+
+    CDEF = """
+        void* polyplug_runtime_create(const void* config);
+        void polyplug_runtime_destroy(void* host);
+    """
+
+    def __init__(self, lib_path: str) -> None:
+        import cffi
+        self.ffi = cffi.FFI()
+        self.ffi.cdef(self.CDEF)
+        self.lib = self.ffi.dlopen(lib_path)
+
+    def create_host_interface(self, config_ptr: int = 0) -> int:
+        """Create runtime and return HostApi pointer.
+
+        Args:
+            config_ptr: Address of a RuntimeConfig struct, or 0 for defaults.
+        """
+        return int(
+            self.ffi.cast(
+                "uintptr_t",
+                self.lib.polyplug_runtime_create(self.ffi.cast("void*", config_ptr)),
+            )
+        )
+
+    def destroy_host_interface(self, host: int) -> None:
+        """Destroy HostApi and runtime."""
+        self.lib.polyplug_runtime_destroy(self.ffi.cast("void*", host))
+
+    def load_host_interface(self, host: int) -> HostApi:
+        """Load HostApi struct from pointer (via ctypes)."""
+        return HostApi.from_address(host)
+
+
+def get_backend() -> str:
+    """Return the current FFI backend name ('cffi' or 'ctypes')."""
+    return _BACKEND
+
+
+def _resolve_lib_path() -> str:
+    env_path: str | None = os.getenv("POLYPLUG_LIB")
+    if env_path:
+        return env_path
+
+    import ctypes.util
+    found: str | None = ctypes.util.find_library(_LIB_NAME)
+    if found is None:
+        return "libpolyplug.so"
+    return found
+
+
+def _create_backend(lib_path: str) -> Backend:
+    """Create the appropriate backend based on availability."""
+    if _cffi_available:
+        return CFFIBackend(lib_path)
+    return CTypesBackend(lib_path)
+
+
+def _read_c_string(ptr: int, length: int) -> str:
+    """Read a C string from a pointer and length."""
+    if ptr == 0 or length == 0:
+        return ""
+    return ctypes.string_at(ptr, length).decode("utf-8", errors="replace")
+
+
+class Runtime:
+    """polyplug runtime for loading and managing plugins.
+
+    Holds HostApi pointer and calls methods through struct fields.
+
+    All configuration is per-instance (Rule 12: no class-level statics shared
+    across runtimes): pass ``config`` and ``on_reload`` to the constructor.
+    The ctypes callback wrapper and host-contract keepalives live on the
+    instance and die with it.
+    """
+
+    def __init__(
+        self,
+        config: Optional["RuntimeConfig"] = None,
+        on_reload: Optional[Callable[[ReloadPhase], None]] = None,
+    ) -> None:
+        lib_path: str = _resolve_lib_path()
+        self._backend: Backend = _create_backend(lib_path)
+        self.ctypes = ctypes
+
+        # Per-instance reload-callback and config state (set before create so
+        # the C callback wrapper outlives the create call).
+        self._on_reload_cb: Optional[Callable[[ReloadPhase], None]] = on_reload
+        self._config: Optional["RuntimeConfig"] = config
+        self._c_callback: Optional[ctypes.CFUNCTYPE] = None
+        self._runtime_config: Optional[RuntimeConfig] = None
+
+        # Per-instance host-contract keepalives: registered interface structs
+        # (with their thunks/stubs anchored on `_keepalive`), keyed by
+        # contract_id. The runtime holds raw pointers into these for its whole
+        # lifetime, so they must stay alive on THIS instance (Rule 12).
+        self._host_contract_interfaces: dict[int, HostContractInterface] = {}
+
+        # Create HostApi (options or default)
+        if self._on_reload_cb is not None or self._config is not None:
+            host_ptr: int = self._create_runtime_with_options()
+        else:
+            host_ptr = self._backend.create_host_interface()
+
+        if host_ptr == 0:
+            raise RuntimeError("polyplug_runtime_create returned null")
+
+        # Store HostApi pointer and load struct
+        self._host: int = host_ptr
+        self._host_struct: HostApi = self._backend.load_host_interface(host_ptr)
+
+        # The HostApi struct fields are already fully-typed C function
+        # pointers (CFUNCTYPE with the canonical ABI signatures from abi.py:
+        # out-param ABI — these return None and write their AbiError through a
+        # trailing pointer passed as ctypes.byref(err)). Cache them directly —
+        # re-wrapping in a hand-rolled CFUNCTYPE would both duplicate the
+        # signature and risk drift from the canonical type.
+        self._load_bundle_fn = self._host_struct.load_bundle
+        self._reload_bundle_fn = self._host_struct.reload_bundle
+        self._unload_bundle_fn = self._host_struct.unload_bundle
+        self._find_guest_contract_fn = self._host_struct.find_guest_contract
+        self._find_all_fn = self._host_struct.find_all_guest_contracts
+        self._resolve_fn = self._host_struct.resolve_guest_contract
+        self._get_last_error_fn = self._host_struct.get_last_error
+        self._get_error_len_fn = self._host_struct.get_error_len
+        self._register_host_contract_fn = self._host_struct.register_host_contract
+        self._register_loader_fn = self._host_struct.register_loader
+        self._free_fn = self._host_struct.free
+
+    def _create_runtime_with_options(self) -> int:
+        """Create runtime via polyplug_runtime_create with a RuntimeConfig.
+
+        The RuntimeConfig (48 bytes) has:
+        - compatibility (u32)
+        - hot_reload_enabled (bool/u8)
+        - on_reload (fn pointer or null)
+        - on_reload_user_data (pointer or null)
+        - log (fn pointer or null)
+        - log_user_data (pointer or null)
+        - log_max_level (u32)
+
+        The runtime only borrows the config for the duration of the build,
+        but the config is retained on the instance so the C callback wrapper
+        (referenced by `on_reload`) is not garbage-collected while in use.
+        """
+        config = RuntimeConfig()
+        config.hot_reload_enabled = False
+        config.compatibility = COMPATIBILITY_STRICT
+
+        if self._config is not None:
+            config.hot_reload_enabled = bool(self._config.hot_reload_enabled)
+            if hasattr(self._config, "compatibility"):
+                config.compatibility = self._config.compatibility
+
+        if self._on_reload_cb is not None:
+            self._c_callback = self._make_c_callback()
+            # The generated field type erases the pointee (c_void_p); the typed
+            # callback (POINTER(AbiReloadPhase) param) is cast to it. The
+            # original wrapper stays referenced via self._c_callback so the
+            # ctypes thunk is not garbage-collected while the runtime lives.
+            config.on_reload = ctypes.cast(self._c_callback, type(config.on_reload))
+        else:
+            config.on_reload = ctypes.cast(None, type(config.on_reload))
+
+        self._runtime_config = config
+        return self._backend.create_host_interface(ctypes.addressof(config))
+
+    def __del__(self) -> None:
+        host_ptr: int = getattr(self, "_host", 0)
+        backend: Backend = getattr(self, "_backend", None)
+        if host_ptr != 0 and backend is not None:
+            backend.destroy_host_interface(host_ptr)
+            self._host = 0
+
+    def _make_c_callback(self) -> ctypes.CFUNCTYPE:
+        """Internal: Create a C-compatible callback wrapper bound to THIS instance.
+
+        The wrapper never raises: a Python exception inside a ctypes callback
+        is swallowed by ctypes (the callback silently dies), so the phase-type
+        conversion is total (unknown discriminants pass through as the raw
+        ``int``) and the user callback is wrapped in a catch-all that logs to
+        stderr.
+        """
+        user_callback: Callable[[ReloadPhase], None] = self._on_reload_cb  # type: ignore[assignment]
+
+        @ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.POINTER(AbiReloadPhase))
+        def c_callback(_user_data: int, abi_phase_ptr: "ctypes._Pointer[AbiReloadPhase]") -> None:
+            try:
+                if not abi_phase_ptr:
+                    # The runtime contract guarantees a non-null pointer; this
+                    # guard is pure defence-in-depth.
+                    return
+                # The pointee is valid only for the duration of this call; all
+                # fields (and the strings they reference) are copied into the
+                # Python-level ReloadPhase below before the callback returns.
+                abi_phase: AbiReloadPhase = abi_phase_ptr.contents
+                raw_type: int = abi_phase.phase_type
+                # Total conversion: ReloadPhaseType(raw) raises ValueError on an
+                # unknown discriminant, which ctypes would swallow — fall back to
+                # the raw int and warn instead.
+                if raw_type in ReloadPhaseType._value2member_map_:
+                    phase_type: ReloadPhaseType | int = ReloadPhaseType(raw_type)
+                else:
+                    phase_type = raw_type
+                    print(
+                        f"polyplug: unknown reload phase type {raw_type}; "
+                        "passing raw value through",
+                        file=sys.stderr,
+                    )
+                reason: str = _read_c_string(
+                    abi_phase.reason.ptr, abi_phase.reason.len
+                )
+                phase = ReloadPhase(
+                    type=phase_type,
+                    bundle_id=abi_phase.bundle_id,
+                    bundle_name=_read_c_string(
+                        abi_phase.bundle_name.ptr, abi_phase.bundle_name.len
+                    ),
+                    reason=reason if reason else None,
+                )
+                user_callback(phase)
+            except Exception as e:  # noqa: BLE001 — must not unwind across the C ABI
+                print(f"polyplug: reload callback error: {e}", file=sys.stderr)
+
+        return c_callback
+
+    def _ensure_host(self) -> int:
+        if self._host == 0:
+            raise RuntimeError("Runtime is closed")
+        return self._host
+
+    def _get_error(self) -> str:
+        """Get last error message from HostApi."""
+        host: int = self._ensure_host()
+        error_len: int = self._get_error_len_fn(host)
+        if error_len == 0:
+            return ""
+
+        buf = (ctypes.c_uint8 * error_len)()
+        written: int = self._get_last_error_fn(host, buf, error_len)
+        if written <= 0:
+            return ""
+        return bytes(buf[:written]).decode("utf-8", errors="replace")
+
+    def _check_error(self, code: int, context: str) -> None:
+        """Check error code and raise if non-zero."""
+        if code == 0:
+            return
+        msg: str = self._get_error()
+        if msg:
+            raise RuntimeError(msg)
+        raise RuntimeError(f"{context} failed with code {code}")
+
+    def load_bundle(self, path: str | Path) -> None:
+        """Load a plugin bundle from path."""
+        host: int = self._ensure_host()
+        path_bytes: bytes = str(Path(path)).encode("utf-8")
+        buf = (ctypes.c_uint8 * len(path_bytes))(*path_bytes)
+        err: AbiError = AbiError()
+        self._load_bundle_fn(host, buf, len(path_bytes), ctypes.byref(err))
+        self._check_error(err.code, "load_bundle")
+
+    def reload_bundle(self, path: str | Path) -> None:
+        """Hot-reload a plugin bundle."""
+        host: int = self._ensure_host()
+        path_bytes: bytes = str(Path(path)).encode("utf-8")
+        buf = (ctypes.c_uint8 * len(path_bytes))(*path_bytes)
+        err: AbiError = AbiError()
+        self._reload_bundle_fn(host, buf, len(path_bytes), ctypes.byref(err))
+        self._check_error(err.code, "reload_bundle")
+
+    def unload_bundle(self, bundle_id: int) -> None:
+        """Unload a plugin bundle by bundle ID."""
+        host: int = self._ensure_host()
+        err: AbiError = AbiError()
+        self._unload_bundle_fn(host, bundle_id, ctypes.byref(err))
+        self._check_error(err.code, "unload_bundle")
+
+    def find_guest_contract(self, contract_id: int, min_version: int) -> GuestContractHandle:
+        """Find a guest contract by contract_id and minimum version.
+
+        Returns a GuestContractHandle struct (index: u32, generation: u32).
+        The null/not-found sentinel has index == 0xFFFFFFFF.
+        """
+        host: int = self._ensure_host()
+        return self._find_guest_contract_fn(host, contract_id, min_version)
+
+    def find_all_by_contract(self, contract_id: int, min_version: int) -> list[GuestContractHandle]:
+        """Find all guest contracts matching contract_id."""
+        host: int = self._ensure_host()
+        # `find_all_guest_contracts` returns an `Array` struct BY VALUE
+        # (#[repr(C)] { items: *mut T, len: usize, align: usize } = 24 bytes).
+        # The CFUNCTYPE restype is the `Array` Structure, so ctypes performs the
+        # sret struct-return ABI and `array` is a populated `Array` instance —
+        # NOT a pointer. Reading its fields directly is correct; treating the
+        # result as a pointer (the old behavior) misread the sret register.
+        array: Array = self._find_all_fn(host, contract_id, min_version)
+
+        array_data: int = array.items or 0
+        array_len: int = array.len
+        if array_len == 0 or array_data == 0:
+            return []
+
+        # GuestContractHandle is `#[repr(C)] { index: u32, generation: u32 }` = 8 bytes,
+        # so the array has an 8-byte element stride and each element is read as a full struct.
+        element_size: int = ctypes.sizeof(GuestContractHandle)
+        handles: list[GuestContractHandle] = []
+        for i in range(array_len):
+            handle: GuestContractHandle = GuestContractHandle.from_address(array_data + i * element_size)
+            handles.append(handle)
+
+        # Free the array via host->free using the same size/align the runtime
+        # allocated with: size = len * sizeof(element), align = array.align.
+        self._free_fn(host, array_data, array_len * element_size, array.align)
+
+        return handles
+
+    def resolve_guest_contract(self, handle: GuestContractHandle) -> int:
+        """Resolve a guest contract handle to a GuestContractInterface pointer."""
+        # Null handle sentinel has index == u32::MAX (0xFFFFFFFF).
+        if handle.index == _NULL_HANDLE_INDEX:
+            raise RuntimeError("null plugin handle")
+        host: int = self._ensure_host()
+        return self._resolve_fn(host, handle)
+
+    def release_plugin(self, resolve_handle: int) -> None:
+        """Release a resolve handle (no-op in HostApi model, managed by registry)."""
+        # In HostApi model, resolve handles are borrowed references
+        # No explicit release needed - the registry manages lifetimes
+        pass
+
+    def register_host_contract(self, interface: HostContractInterface) -> None:
+        """Register a fully populated host contract interface with the runtime.
+
+        The interface comes from a GENERATED factory
+        (``generated/host/interface_factories.py``: ``create_*_interface``),
+        which builds the thunks, instance stubs, and dispatch table with the
+        correct ABI signatures and anchors them on ``interface._keepalive``.
+
+        The interface struct is kept alive on THIS instance (per-runtime,
+        keyed by contract_id) — never on the class, where a second runtime
+        registering the same contract_id would clobber the first (Rule 12).
+        The runtime holds the raw pointer for its whole lifetime.
+        """
+        host: int = self._ensure_host()
+
+        contract_id: int = interface.contract_id
+        # Instance-owned keepalive: the struct address must stay stable and
+        # alive for the runtime lifetime.
+        self._host_contract_interfaces[contract_id] = interface
+
+        interface_ptr = ctypes.addressof(interface)
+        err: AbiError = AbiError()
+        self._register_host_contract_fn(host, interface_ptr, ctypes.byref(err))
+        if err.code == AbiErrorCode.DuplicateProvider:
+            raise RuntimeError(f"duplicate host contract: contract_id={contract_id}")
+        self._check_error(err.code, "register_host_contract")
+
+    def register_loader(self, loader_ptr: int) -> None:
+        """Register a language loader with the runtime via HostApi.
+
+        Args:
+            loader_ptr: Opaque loader pointer from the loader cdylib's create function.
+        """
+        host: int = self._ensure_host()
+        err: AbiError = AbiError()
+        self._register_loader_fn(host, loader_ptr, ctypes.byref(err))
+        self._check_error(err.code, "register_loader")

polyplug-0.1.0/polyplug/scanner.py

@@ -0,0 +1,47 @@
+"""Scanner module for discovering polyplug plugin bundles."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Tuple
+
+
+@dataclass
+class Manifest:
+    """Plugin bundle manifest."""
+
+    name: str
+    version: str = "0.0.0"
+    provides: List[str] | None = None
+
+
+def scan_dir(dir_path: str) -> List[Tuple[str, Manifest]]:
+    """Scan a directory for polyplug plugin bundles.
+
+    Args:
+        dir_path: Path to directory containing plugin bundles
+
+    Returns:
+        List of (bundle_path, Manifest) tuples
+    """
+    bundles: List[Tuple[str, Manifest]] = []
+
+    for entry in os.scandir(dir_path):
+        if not entry.is_dir():
+            continue
+
+        manifest_path = os.path.join(entry.path, "manifest.toml")
+        if os.path.exists(manifest_path):
+            with open(manifest_path, "rb") as f:
+                data = tomllib.load(f)
+            manifest = Manifest(
+                name=data.get("name", ""),
+                version=data.get("version", "0.0.0"),
+                provides=data.get("provides"),
+            )
+            bundles.append((entry.path, manifest))
+
+    return bundles

polyplug-0.1.0/polyplug.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: polyplug
+Version: 0.1.0
+Summary: Python host library for the polyplug plugin runtime
+License: MIT
+Project-URL: Homepage, https://github.com/polyplug/polyplug
+Project-URL: Documentation, https://github.com/polyplug/polyplug#readme
+Project-URL: Repository, https://github.com/polyplug/polyplug.git
+Project-URL: Issues, https://github.com/polyplug/polyplug/issues
+Keywords: polyplug,plugin,runtime,ffi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: polyplug-abi
+Provides-Extra: native
+Requires-Dist: polyplug-loaders-native; extra == "native"
+Provides-Extra: python
+Requires-Dist: polyplug-loaders-python; extra == "python"
+Provides-Extra: lua
+Requires-Dist: polyplug-loaders-lua; extra == "lua"
+Provides-Extra: js
+Requires-Dist: polyplug-loaders-js; extra == "js"
+Provides-Extra: dotnet
+Requires-Dist: polyplug-loaders-dotnet; extra == "dotnet"
+Provides-Extra: all
+Requires-Dist: polyplug-loaders-native; extra == "all"
+Requires-Dist: polyplug-loaders-python; extra == "all"
+Requires-Dist: polyplug-loaders-lua; extra == "all"
+Requires-Dist: polyplug-loaders-js; extra == "all"
+Requires-Dist: polyplug-loaders-dotnet; extra == "all"

polyplug-0.1.0/polyplug.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+pyproject.toml
+polyplug/__init__.py
+polyplug/runtime.py
+polyplug/scanner.py
+polyplug.egg-info/PKG-INFO
+polyplug.egg-info/SOURCES.txt
+polyplug.egg-info/dependency_links.txt
+polyplug.egg-info/requires.txt
+polyplug.egg-info/top_level.txt
+polyplug/_native/__init__.py
+polyplug/_native/linux-x64/libpolyplug.so
+polyplug/_native/macos-arm64/libpolyplug.dylib
+polyplug/_native/windows-x64/polyplug.dll
+tests/test_host_contract_runtime.py
+tests/test_reload_runtime.py
+tests/test_runtime_config_c.py

polyplug-0.1.0/polyplug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

polyplug-0.1.0/polyplug.egg-info/requires.txt

@@ -0,0 +1,23 @@
+polyplug-abi
+
+[all]
+polyplug-loaders-native
+polyplug-loaders-python
+polyplug-loaders-lua
+polyplug-loaders-js
+polyplug-loaders-dotnet
+
+[dotnet]
+polyplug-loaders-dotnet
+
+[js]
+polyplug-loaders-js
+
+[lua]
+polyplug-loaders-lua
+
+[native]
+polyplug-loaders-native
+
+[python]
+polyplug-loaders-python

polyplug-0.1.0/polyplug.egg-info/top_level.txt

@@ -0,0 +1 @@
+polyplug

polyplug-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "polyplug"
+version = "0.1.0"
+description = "Python host library for the polyplug plugin runtime"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["polyplug", "plugin", "runtime", "ffi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "polyplug-abi",
+]
+
+[project.optional-dependencies]
+native = ["polyplug-loaders-native"]
+python = ["polyplug-loaders-python"]
+lua = ["polyplug-loaders-lua"]
+js = ["polyplug-loaders-js"]
+dotnet = ["polyplug-loaders-dotnet"]
+all = [
+    "polyplug-loaders-native",
+    "polyplug-loaders-python",
+    "polyplug-loaders-lua",
+    "polyplug-loaders-js",
+    "polyplug-loaders-dotnet",
+]
+
+[project.urls]
+Homepage = "https://github.com/polyplug/polyplug"
+Documentation = "https://github.com/polyplug/polyplug#readme"
+Repository = "https://github.com/polyplug/polyplug.git"
+Issues = "https://github.com/polyplug/polyplug/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["polyplug*"]
+
+[tool.setuptools.package-data]
+polyplug = ["_native/**/*"]

polyplug-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

polyplug-0.1.0/tests/test_host_contract_runtime.py

@@ -0,0 +1,173 @@
+"""sdks/python/host/tests/test_host_contract_runtime.py
+
+REAL-runtime host-contract test (mirrors sdks/lua/host/tests/test_reload_runtime.lua).
+
+`test_runtime_config_c.py` covers SDK-side ctypes types only — it can never
+catch a broken FFI path. This test drives the actual flow: a Python host
+creates a runtime through the SDK, registers the `host.logger` contract via
+the GENERATED interface factory (which routes dispatch through the native
+trampoline `polyplug_python_host_vm_dispatch` exported by the python loader
+cdylib — ctypes cannot create struct-returning callbacks), loads the REAL
+rust `reporter` example plugin through the native loader, and dispatches its
+`report` function. The plugin resolves `host.logger` across the C ABI and
+calls back into this Python implementation — including `log_with_level`,
+whose first parameter is the `LogLevel` ENUM (proving the repr-ctype enum
+marshalling at runtime, not just at the generated-string level).
+
+Skip-honestly policy (matches sdks/lua/host/tests/test_reload_runtime.lua):
+when the required environment is absent the test FAILS LOUDLY with
+instructions — a runtime test that silently passes hides exactly the
+never-run breakage class it exists to catch.
+
+Run from repo root:
+  cargo build --release -p polyplug -p polyplug_native -p polyplug_python
+  bash examples/build_all.sh
+  POLYPLUG_LIB=$PWD/target/release/libpolyplug.so \
+  POLYPLUG_NATIVE_LIB=$PWD/target/release/libpolyplug_native.so \
+  POLYPLUG_PYTHON_LIB=$PWD/target/release/libpolyplug_python.so \
+  python3 sdks/python/host/tests/test_host_contract_runtime.py
+
+Or via the justfile recipe: just test-host-python
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+# ─── Path setup ───────────────────────────────────────────────────────────────
+# Resolve everything from this script's own directory (sdks/python/host/tests/),
+# mirroring the PYTHON_HOST_PATH used by examples/verify_hosts.sh.
+_TESTS_DIR: Path = Path(__file__).resolve().parent
+_HOST_DIR: Path = _TESTS_DIR.parent  # sdks/python/host
+_PYTHON_SDK_DIR: Path = _HOST_DIR.parent  # sdks/python
+_REPO_ROOT: Path = _PYTHON_SDK_DIR.parent.parent  # repo root
+
+sys.path.insert(0, str(_HOST_DIR))
+sys.path.insert(0, str(_PYTHON_SDK_DIR / "polyplug_abi"))
+sys.path.insert(0, str(_PYTHON_SDK_DIR))
+sys.path.insert(0, str(_PYTHON_SDK_DIR / "loaders" / "native"))
+# Generated host bindings for examples/api.toml (host.logger factory + callers).
+sys.path.insert(0, str(_REPO_ROOT / "examples" / "hosts" / "python" / "generated"))
+
+# ─── Skip-honestly: a runtime test must never silently pass ───────────────────
+_MISSING: list[str] = [
+    name
+    for name in ("POLYPLUG_LIB", "POLYPLUG_NATIVE_LIB", "POLYPLUG_PYTHON_LIB")
+    if not os.environ.get(name)
+]
+if _MISSING:
+    sys.stderr.write(
+        "FATAL: "
+        + ", ".join(_MISSING)
+        + " not set — this runtime test must not silently pass.\n"
+        "Build the core and point the test at it:\n"
+        "  cargo build --release -p polyplug -p polyplug_native -p polyplug_python\n"
+        "  export POLYPLUG_LIB=$PWD/target/release/libpolyplug.so\n"
+        "  export POLYPLUG_NATIVE_LIB=$PWD/target/release/libpolyplug_native.so\n"
+        "  export POLYPLUG_PYTHON_LIB=$PWD/target/release/libpolyplug_python.so\n"
+    )
+    sys.exit(1)
+
+_REPORTER_BUNDLE: Path = _REPO_ROOT / "examples" / "plugins" / "rust_reporter"
+if not _REPORTER_BUNDLE.is_dir():
+    sys.stderr.write(
+        f"FATAL: reporter example bundle missing: {_REPORTER_BUNDLE}\n"
+        "This runtime test drives the REAL rust reporter plugin — build it first:\n"
+        "  bash examples/build_all.sh\n"
+    )
+    sys.exit(1)
+
+from polyplug import Runtime  # noqa: E402  (sys.path setup above)
+from polyplug_abi import StringView, to_str  # noqa: E402
+from polyplug_loaders_native import register_native_loader  # noqa: E402
+from host.contracts import HostLogger  # noqa: E402
+from host.interface_factories import create_host_logger_interface  # noqa: E402
+from host.types import LogLevel  # noqa: E402
+from host.callers import (  # noqa: E402
+    DATA_REPORTER_CONTRACT_ID,
+    DataReporterContractCaller,
+)
+
+
+def _str_view(s: str, keepalive: list) -> StringView:
+    """Build a StringView over a UTF-8 buffer kept alive via `keepalive`
+    (mirrors examples/hosts/python/main.py)."""
+    data: bytes = s.encode("utf-8")
+    buf: ctypes.Array = ctypes.create_string_buffer(data, len(data))
+    keepalive.append(buf)
+    return StringView(ptr=ctypes.cast(buf, ctypes.c_void_p), len=len(data))
+
+
+class CapturingLogger(HostLogger):
+    """Records every call the plugin makes across the C ABI."""
+
+    def __init__(self) -> None:
+        self.entries: list[tuple[str, LogLevel | None, str]] = []
+
+    def log(self, message: str) -> None:
+        self.entries.append(("log", None, message))
+
+    def log_with_level(self, level: LogLevel, message: str) -> None:
+        self.entries.append(("log_with_level", level, message))
+
+
+def main() -> None:
+    rt = Runtime()
+    register_native_loader(rt)
+
+    # Register host.logger through the GENERATED factory: dispatch routes
+    # through the python loader cdylib's native trampoline into the scalar
+    # ctypes dispatcher built by the factory.
+    logger = CapturingLogger()
+    bridge_lib: ctypes.CDLL = ctypes.CDLL(os.environ["POLYPLUG_PYTHON_LIB"])
+    rt.register_host_contract(create_host_logger_interface(logger, bridge_lib))
+
+    rt.load_bundle(_REPORTER_BUNDLE)
+
+    handle = rt.find_guest_contract(DATA_REPORTER_CONTRACT_ID, 0)
+    assert handle.index != 0xFFFFFFFF, "data.Reporter contract must be registered"
+    caller = DataReporterContractCaller.create(handle, rt._ensure_host(), owner=rt)
+
+    report_input: str = "TRANSFORMED:NAME|value (transformed)|43"
+    keepalive: list = []
+    result_sv: StringView = caller.report(_str_view(report_input, keepalive))
+    result: str = to_str(result_sv)
+    assert result == "Report: NAME has value 'value (transformed)' with count 43", (
+        f"unexpected report output: {result!r}"
+    )
+
+    # The plugin must have called back into the host across the ABI: one plain
+    # log plus four log_with_level calls with REAL LogLevel enum values.
+    expected: list[tuple[str, LogLevel | None, str]] = [
+        ("log", None, f"[plugin] Starting report for: {report_input}"),
+        ("log_with_level", LogLevel.INFO, "[plugin] Step 1: Parsing input"),
+        ("log_with_level", LogLevel.DEBUG, f"[plugin] Input length: {len(report_input)}"),
+        ("log_with_level", LogLevel.WARN, "[plugin] Step 2: Processing data"),
+        ("log_with_level", LogLevel.ERROR, "[plugin] Step 3: Finalizing report"),
+    ]
+    assert logger.entries == expected, (
+        f"host.logger callbacks mismatch:\n  got:      {logger.entries}\n"
+        f"  expected: {expected}"
+    )
+
+    # Enum params must arrive as the generated IntEnum, not a bare int —
+    # the dispatcher wraps the raw repr u32 back into LogLevel.
+    levels: list[LogLevel | None] = [entry[1] for entry in logger.entries[1:]]
+    assert all(isinstance(level, LogLevel) for level in levels), (
+        f"levels must be LogLevel instances: {[type(level) for level in levels]}"
+    )
+
+    print("PASS: python host registered host.logger via generated factory")
+    print("PASS: rust reporter plugin called log() across the ABI")
+    print("PASS: log_with_level() delivered REAL LogLevel enum values:")
+    for kind, level, message in logger.entries:
+        level_str: str = level.name if isinstance(level, LogLevel) else "-"
+        print(f"  [{kind}][{level_str}] {message}")
+    print("test_host_contract_runtime: all assertions passed")
+
+
+if __name__ == "__main__":
+    main()

polyplug-0.1.0/tests/test_reload_runtime.py

@@ -0,0 +1,152 @@
+"""sdks/python/host/tests/test_reload_runtime.py
+
+REAL-runtime hot-reload notification test (mirrors
+sdks/lua/host/tests/test_reload_runtime.lua and
+sdks/js/host/tests/reload_runtime_test.ts).
+
+`test_runtime_config_c.py` covers the SDK-side RuntimeConfig/ReloadPhase ctypes
+types only — it builds local structs and asserts on them, which can never catch
+a broken FFI path. This test drives the actual flow: create a runtime through
+the Python host SDK with an `on_reload` callback (a real ctypes CFUNCTYPE for
+the `void(*)(void*, const ReloadPhase*)` ABI signature), load the native reload
+fixture bundle, trigger a reload through the runtime, and assert the callback
+fired with REAL phase data delivered across the C ABI.
+
+Skip-honestly policy (matches sdks/lua/host/tests/test_reload_runtime.lua):
+when POLYPLUG_LIB / POLYPLUG_NATIVE_LIB are absent the test FAILS LOUDLY with
+instructions — a runtime test that silently passes hides exactly the never-run
+breakage class it exists to catch.
+
+Run from repo root:
+  cargo build --release -p polyplug -p polyplug_native
+  bash tests/fixtures/build_all.sh
+  POLYPLUG_LIB=$PWD/target/release/libpolyplug.so \
+  POLYPLUG_NATIVE_LIB=$PWD/target/release/libpolyplug_native.so \
+  python3 sdks/python/host/tests/test_reload_runtime.py
+
+Or via the justfile recipe: just test-host-python
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# ─── Path setup ───────────────────────────────────────────────────────────────
+# Resolve everything from this script's own directory (sdks/python/host/tests/),
+# mirroring test_host_contract_runtime.py.
+_TESTS_DIR: Path = Path(__file__).resolve().parent
+_HOST_DIR: Path = _TESTS_DIR.parent  # sdks/python/host
+_PYTHON_SDK_DIR: Path = _HOST_DIR.parent  # sdks/python
+_REPO_ROOT: Path = _PYTHON_SDK_DIR.parent.parent  # repo root
+
+sys.path.insert(0, str(_HOST_DIR))
+sys.path.insert(0, str(_PYTHON_SDK_DIR / "polyplug_abi"))
+sys.path.insert(0, str(_PYTHON_SDK_DIR))
+sys.path.insert(0, str(_PYTHON_SDK_DIR / "loaders" / "native"))
+
+# ─── Skip-honestly: a runtime test must never silently pass ───────────────────
+_MISSING: list[str] = [
+    name
+    for name in ("POLYPLUG_LIB", "POLYPLUG_NATIVE_LIB")
+    if not os.environ.get(name)
+]
+if _MISSING:
+    sys.stderr.write(
+        "FATAL: "
+        + ", ".join(_MISSING)
+        + " not set — this runtime test must not silently pass.\n"
+        "Build the core and point the test at it:\n"
+        "  cargo build --release -p polyplug -p polyplug_native\n"
+        "  export POLYPLUG_LIB=$PWD/target/release/libpolyplug.so\n"
+        "  export POLYPLUG_NATIVE_LIB=$PWD/target/release/libpolyplug_native.so\n"
+    )
+    sys.exit(1)
+
+# Platform-specific cdylib naming (matches tests/fixtures/build_all.sh):
+# `<name>.dll` on Windows (no `lib` prefix), `lib<name>.dylib` on macOS,
+# `lib<name>.so` on Linux.
+if sys.platform == "win32":
+    _V1_LIB_NAME: str = "reload_plugin_v1.dll"
+    _V2_LIB_NAME: str = "reload_plugin_v2.dll"
+elif sys.platform == "darwin":
+    _V1_LIB_NAME = "libreload_plugin_v1.dylib"
+    _V2_LIB_NAME = "libreload_plugin_v2.dylib"
+else:
+    _V1_LIB_NAME = "libreload_plugin_v1.so"
+    _V2_LIB_NAME = "libreload_plugin_v2.so"
+
+_FIXTURES_DIR: Path = _REPO_ROOT / "tests" / "fixtures"
+_V1_DIR: Path = _FIXTURES_DIR / "reload_plugin_v1"
+# The reload target is the v2 cdylib INSIDE its bundle dir — the runtime reads
+# the sibling manifest.toml during reload (mirrors integration_reload.rs).
+_V2_LIB: Path = _FIXTURES_DIR / "reload_plugin_v2" / _V2_LIB_NAME
+
+for _fixture in (_V1_DIR / "manifest.toml", _V1_DIR / _V1_LIB_NAME, _V2_LIB):
+    if not _fixture.is_file():
+        sys.stderr.write(
+            f"FATAL: reload fixture missing: {_fixture}\n"
+            "Run `bash tests/fixtures/build_all.sh` first.\n"
+        )
+        sys.exit(1)
+
+from polyplug import Runtime  # noqa: E402  (sys.path setup above)
+from polyplug_abi import (  # noqa: E402
+    ReloadPhase,
+    RuntimeConfig,
+    bundle_id,
+)
+from polyplug_loaders_native import register_native_loader  # noqa: E402
+
+# Name from tests/fixtures/reload_plugin_v1/manifest.toml; the bundle id is
+# FNV-1a 64 of the name (TRUST_MODEL §2) — computed via the SDK helper, never
+# hand-rolled.
+_V1_BUNDLE_ID: int = bundle_id("reload_plugin_v1")
+
+
+def main() -> None:
+    phases: list[ReloadPhase] = []
+
+    config = RuntimeConfig()
+    config.hot_reload_enabled = True
+    rt = Runtime(config=config, on_reload=phases.append)
+    register_native_loader(rt)
+
+    rt.load_bundle(_V1_DIR)
+    assert not phases, f"no reload phases expected before the reload, got: {phases}"
+
+    rt.reload_bundle(_V2_LIB)
+
+    assert len(phases) >= 2, (
+        f"reload must deliver at least Preparing + Reloaded, got {len(phases)}: {phases}"
+    )
+
+    first: ReloadPhase = phases[0]
+    assert first.is_preparing(), f"first phase must be Preparing, got: {first!r}"
+    assert first.bundle_id == _V1_BUNDLE_ID, (
+        "Preparing phase must carry the real bundle id from the manifest "
+        f"(got {first.bundle_id}, want {_V1_BUNDLE_ID})"
+    )
+    assert first.bundle_name == "reload_plugin_v1", (
+        f"Preparing phase must carry the real bundle name (got {first.bundle_name!r})"
+    )
+    # Non-Failed phases carry the null-view reason; the SDK surfaces it as None.
+    assert first.reason is None, (
+        f"non-Failed phase must carry the null-view reason as None (got {first.reason!r})"
+    )
+
+    assert any(phase.is_reloaded() for phase in phases), (
+        f"a Reloaded phase must follow, got: {phases}"
+    )
+
+    print("PASS: no reload phases before the reload")
+    print("PASS: reload delivered Preparing with real bundle_id/bundle_name/null reason")
+    print("PASS: a Reloaded phase followed")
+    for phase in phases:
+        print(f"  {phase!r}")
+    print("test_reload_runtime: all assertions passed")
+
+
+if __name__ == "__main__":
+    main()

polyplug-0.1.0/tests/test_runtime_config_c.py

@@ -0,0 +1,76 @@
+"""Tests for Python SDK RuntimeConfig matching polyplug_abi RuntimeConfig."""
+
+import ctypes
+
+
+class Compatibility(ctypes.c_uint32):
+    """Compatibility enum matching polyplug_abi::Compatibility."""
+    Strict = 0
+    Relaxed = 1
+    Yolo = 2
+
+
+# Nullable function pointer (Option<fn>). Can be set to None.
+_runtime_config_on_reload_t = ctypes.CFUNCTYPE(None, ctypes.c_void_p)
+
+
+# Define RuntimeConfig directly to test without native library loading
+class RuntimeConfig(ctypes.Structure):
+    """FFI RuntimeConfig matching polyplug_abi::RuntimeConfig (24-byte prefix)."""
+
+    _fields_ = [
+        ("compatibility", Compatibility),            # offset 0, 4 bytes
+        ("hot_reload_enabled", ctypes.c_bool),       # offset 4, 1 byte (+3 pad)
+        ("on_reload", _runtime_config_on_reload_t),  # offset 8, 8 bytes
+        ("on_reload_user_data", ctypes.c_void_p),    # offset 16, 8 bytes
+    ]
+
+
+COMPATIBILITY_STRICT = 0
+COMPATIBILITY_RELAXED = 1
+COMPATIBILITY_YOLO = 2
+
+
+def test_runtime_config_has_compatibility_field():
+    """RuntimeConfig must have compatibility field."""
+    fields = [f[0] for f in RuntimeConfig._fields_]
+    assert "compatibility" in fields, f"Missing compatibility field. Fields: {fields}"
+
+
+def test_runtime_config_has_correct_field_types():
+    """RuntimeConfig field types must match polyplug_abi."""
+    # Check compatibility is a c_uint32 subtype
+    field_types = {f[0]: f[1] for f in RuntimeConfig._fields_}
+    assert issubclass(field_types["compatibility"], ctypes.c_uint32), \
+        f"compatibility must be c_uint32, got {field_types['compatibility']}"
+    assert field_types["hot_reload_enabled"] == ctypes.c_bool, \
+        f"hot_reload_enabled must be c_bool, got {field_types['hot_reload_enabled']}"
+    assert field_types["on_reload"] == _runtime_config_on_reload_t, \
+        f"on_reload must be a function pointer type, got {field_types['on_reload']}"
+
+
+def test_runtime_config_prefix_is_24_bytes():
+    """RuntimeConfig prefix (through on_reload_user_data) must be 24 bytes."""
+    size = ctypes.sizeof(RuntimeConfig)
+    assert size == 24, f"RuntimeConfig prefix must be 24 bytes, got {size}"
+
+
+def test_runtime_config_on_reload_at_offset_8():
+    """on_reload must sit at offset 8 (compatibility + bool + padding)."""
+    assert RuntimeConfig.on_reload.offset == 8
+
+
+def test_compatibility_constants_defined():
+    """Compatibility enum constants must be defined."""
+    assert COMPATIBILITY_STRICT == 0
+    assert COMPATIBILITY_RELAXED == 1
+    assert COMPATIBILITY_YOLO == 2
+
+
+if __name__ == "__main__":
+    test_runtime_config_has_compatibility_field()
+    test_runtime_config_has_correct_field_types()
+    test_runtime_config_prefix_is_24_bytes()
+    test_runtime_config_on_reload_at_offset_8()
+    test_compatibility_constants_defined()
+    print("All tests passed!")