zgc-runtime 0.1.0__tar.gz

zgc_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: zgc-runtime
+Version: 0.1.0
+Summary: Python runtime for ZGC executable artifacts
+Requires-Python: >=3.10

zgc_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zgc-runtime"
+version = "0.1.0"
+description = "Python runtime for ZGC executable artifacts"
+requires-python = ">=3.10"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+zgc = ["py.typed"]

zgc_runtime-0.1.0/setup.cfg

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

zgc_runtime-0.1.0/src/zgc/__init__.py

@@ -0,0 +1,14 @@
+from ._abi import ABI_VERSION, SourceBinding, SourceKind, dtype
+from .runtime import Runtime, Source, Tensor, TensorInfo, load
+
+__all__ = [
+    "ABI_VERSION",
+    "dtype",
+    "Runtime",
+    "Source",
+    "SourceBinding",
+    "SourceKind",
+    "Tensor",
+    "TensorInfo",
+    "load",
+]

zgc_runtime-0.1.0/src/zgc/_abi.py

@@ -0,0 +1,172 @@
+"""ZGC ABI bindings and helpers."""
+from __future__ import annotations
+
+import ctypes
+from enum import IntEnum
+from typing import Protocol, cast, final
+
+ABI_VERSION = 1
+
+
+class Status(IntEnum):
+    OK = 0
+    INVALID_ARGUMENT = 1
+    INVALID_RUNTIME_STORAGE = 2
+    INVALID_SOURCE = 3
+    INVALID_OUTPUT = 4
+    SIZE_MISMATCH = 5
+    ALIGNMENT_MISMATCH = 6
+    INCOMPATIBLE_BINDING = 7
+    MISSING_BINDING = 8
+    BUFFER_TOO_SMALL = 9
+    OUT_OF_MEMORY = 10
+
+
+class dtype(IntEnum):
+    f32 = 1
+    f16 = 2
+    i8 = 3
+    bool = 4
+
+
+class SourceKind(IntEnum):
+    INPUT = 1
+    PARAMETER = 2
+    CONSTANT = 3
+    STATE = 4
+
+
+class SourceBinding(IntEnum):
+    OWNED = 1
+    BOUND = 2
+    EMBEDDED = 3
+
+
+@final
+class TensorDescriptor(ctypes.Structure):
+    _fields_ = [
+        ("dtype", ctypes.c_uint32),
+        ("rank", ctypes.c_uint32),
+        ("element_count", ctypes.c_size_t),
+        ("logical_byte_count", ctypes.c_size_t),
+        ("offset_elements", ctypes.c_size_t),
+        ("shape", ctypes.POINTER(ctypes.c_size_t)),
+        ("strides", ctypes.POINTER(ctypes.c_ssize_t)),
+    ]
+
+
+@final
+class SourceDescriptor(ctypes.Structure):
+    _fields_ = [
+        ("key", ctypes.c_uint32),
+        ("name", ctypes.c_char_p),
+        ("kind", ctypes.c_uint32),
+        ("binding", ctypes.c_uint32),
+        ("tensor", TensorDescriptor),
+    ]
+
+
+def configure(library: ctypes.CDLL) -> None:
+    library.zgc_abi_version.restype = ctypes.c_uint32
+    library.zgc_executable_structural_fingerprint.restype = ctypes.c_uint64
+    library.zgc_runtime_size.restype = ctypes.c_size_t
+    library.zgc_runtime_alignment.restype = ctypes.c_size_t
+    library.zgc_runtime_mutable_bytes.restype = ctypes.c_size_t
+
+    library.zgc_runtime_init.argtypes = [ctypes.c_void_p, ctypes.c_size_t]
+    library.zgc_runtime_init.restype = ctypes.c_int
+    library.zgc_runtime_deinit.argtypes = [ctypes.c_void_p]
+    library.zgc_runtime_deinit.restype = None
+    library.zgc_runtime_run.argtypes = [ctypes.c_void_p]
+    library.zgc_runtime_run.restype = ctypes.c_int
+
+    library.zgc_executable_source_count.restype = ctypes.c_size_t
+    library.zgc_executable_get_source_descriptor.argtypes = [
+        ctypes.c_size_t,
+        ctypes.POINTER(SourceDescriptor),
+    ]
+    library.zgc_executable_get_source_descriptor.restype = ctypes.c_int
+    library.zgc_runtime_copy_source.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_uint32,
+        ctypes.c_void_p,
+        ctypes.c_size_t,
+    ]
+    library.zgc_runtime_copy_source.restype = ctypes.c_int
+    library.zgc_runtime_bind_source.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_uint32,
+        ctypes.c_void_p,
+        ctypes.c_size_t,
+    ]
+    library.zgc_runtime_bind_source.restype = ctypes.c_int
+
+    library.zgc_executable_output_count.restype = ctypes.c_size_t
+    library.zgc_executable_get_output_descriptor.argtypes = [
+        ctypes.c_size_t,
+        ctypes.POINTER(TensorDescriptor),
+    ]
+    library.zgc_executable_get_output_descriptor.restype = ctypes.c_int
+    library.zgc_runtime_copy_output.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_size_t,
+        ctypes.c_void_p,
+        ctypes.c_size_t,
+    ]
+    library.zgc_runtime_copy_output.restype = ctypes.c_int
+
+
+class Library(Protocol):
+    def zgc_abi_version(self) -> int: ...
+    def zgc_executable_structural_fingerprint(self) -> int: ...
+    def zgc_runtime_size(self) -> int: ...
+    def zgc_runtime_alignment(self) -> int: ...
+    def zgc_runtime_mutable_bytes(self) -> int: ...
+    def zgc_runtime_init(self, runtime: ctypes.c_void_p, size: int) -> int: ...
+    def zgc_runtime_deinit(self, runtime: ctypes.c_void_p) -> None: ...
+    def zgc_runtime_run(self, runtime: ctypes.c_void_p) -> int: ...
+    def zgc_executable_source_count(self) -> int: ...
+    def zgc_executable_get_source_descriptor(self, index: int, output: object) -> int: ...
+    def zgc_runtime_copy_source(
+        self,
+        runtime: ctypes.c_void_p,
+        key: int,
+        data: ctypes.c_void_p,
+        size: int,
+    ) -> int: ...
+    def zgc_runtime_bind_source(
+        self,
+        runtime: ctypes.c_void_p,
+        key: int,
+        data: ctypes.c_void_p,
+        size: int,
+    ) -> int: ...
+    def zgc_executable_output_count(self) -> int: ...
+    def zgc_executable_get_output_descriptor(self, index: int, output: object) -> int: ...
+    def zgc_runtime_copy_output(
+        self,
+        runtime: ctypes.c_void_p,
+        index: int,
+        data: ctypes.c_void_p,
+        size: int,
+    ) -> int: ...
+
+
+def load_library(path: str) -> Library:
+    library = ctypes.CDLL(path)
+    library.zgc_abi_version.restype = ctypes.c_uint32
+    version = library.zgc_abi_version()
+    if version != ABI_VERSION:
+        raise RuntimeError(f"unsupported ZGC ABI version {version}")
+    configure(library)
+    return cast(Library, cast(object, library))
+
+
+def require_ok(status: int, operation: str) -> None:
+    if status == Status.OK:
+        return
+    try:
+        name = Status(status).name.lower()
+    except ValueError:
+        name = f"unknown status {status}"
+    raise RuntimeError(f"{operation} failed: {name}")

zgc_runtime-0.1.0/src/zgc/py.typed

@@ -0,0 +1 @@
+

zgc_runtime-0.1.0/src/zgc/runtime.py

@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+import ctypes
+import struct
+import sys
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from os import PathLike
+from pathlib import Path
+from typing import Literal, Protocol, Self, cast, final
+
+from ._abi import (
+    Library,
+    SourceBinding,
+    SourceDescriptor,
+    SourceKind,
+    TensorDescriptor,
+    load_library,
+    require_ok,
+)
+from ._abi import (
+    dtype as dtype_enum,
+)
+
+
+class _TensorDescriptorFields(Protocol):
+    dtype: int
+    rank: int
+    element_count: int
+    logical_byte_count: int
+    offset_elements: int
+    shape: Sequence[int]
+    strides: Sequence[int]
+
+
+class _SourceDescriptorFields(Protocol):
+    key: int
+    name: bytes | None
+    kind: int
+    binding: int
+    tensor: TensorDescriptor
+
+
+@dataclass(frozen=True)
+class TensorInfo:
+    dtype: dtype_enum
+    shape: tuple[int, ...]
+    strides: tuple[int, ...]
+    element_count: int
+    byte_count: int
+    offset: int
+
+
+@dataclass(frozen=True)
+class Source:
+    key: int
+    name: str
+    kind: SourceKind
+    binding: SourceBinding
+    tensor: TensorInfo
+
+
+@dataclass(frozen=True)
+class Tensor:
+    dtype: dtype_enum
+    shape: tuple[int, ...]
+    _storage: bytearray
+
+    @property
+    def buffer(self) -> memoryview:
+        raw = memoryview(self._storage)
+        return cast(
+            memoryview,
+            raw.cast(  # pyright: ignore[reportCallIssue]
+                _format(self.dtype),  # pyright: ignore[reportArgumentType]
+                shape=list(self.shape),
+            ),
+        )
+
+    @property
+    def values(self) -> tuple[float | int | bool, ...]:
+        return _decode(self.dtype, len(self._storage), self._storage)
+
+    @property
+    def strides(self) -> tuple[int, ...]:
+        return tuple(self.buffer.strides or ())
+
+    def tolist(self) -> list[float | int | bool]:
+        return list(self.values)
+
+
+def _tensor_info(descriptor: TensorDescriptor) -> TensorInfo:
+    fields = cast(_TensorDescriptorFields, cast(object, descriptor))
+    return TensorInfo(
+        dtype=dtype_enum(fields.dtype),
+        shape=tuple(fields.shape[index] for index in range(fields.rank)),
+        strides=tuple(fields.strides[index] for index in range(fields.rank)),
+        element_count=fields.element_count,
+        byte_count=fields.logical_byte_count,
+        offset=fields.offset_elements,
+    )
+
+
+def _format(dtype: dtype_enum) -> Literal["f", "e", "b", "?"]:
+    if dtype is dtype_enum.f32:
+        return "f"
+    if dtype is dtype_enum.f16:
+        return "e"
+    if dtype is dtype_enum.i8:
+        return "b"
+    return "?"
+
+
+def _item_size(dtype: dtype_enum) -> int:
+    return struct.calcsize(f"={_format(dtype)}")
+
+
+def _decode(
+    dtype: dtype_enum,
+    byte_count: int,
+    payload: bytes | bytearray | memoryview,
+) -> tuple[float | int | bool, ...]:
+    element_count = byte_count // _item_size(dtype)
+    return struct.unpack(f"={element_count}{_format(dtype)}", payload)
+
+
+def _native_format(view: memoryview) -> str | None:
+    value = view.format
+    if not value:
+        return None
+    if value[0] in "@=":
+        return value[1:]
+    if value[0] in "<>!":
+        if view.itemsize == 1:
+            return value[1:]
+        native_prefix = "<" if sys.byteorder == "little" else ">"
+        return value[1:] if value[0] == native_prefix else None
+    return value
+
+
+def _buffer_view(info: TensorInfo, values: object) -> memoryview | None:
+    try:
+        view = memoryview(values)  # pyright: ignore[reportArgumentType]
+    except TypeError:
+        return None
+
+    if view.nbytes != info.byte_count:
+        raise ValueError(
+            f"expected {info.byte_count} source bytes, received {view.nbytes}"
+        )
+
+    # Byte-oriented buffers preserve the raw-byte input supported by the ABI.
+    if view.itemsize == 1 and _native_format(view) in {"b", "B", "c"}:
+        return view
+
+    expected_format = _format(info.dtype)
+    if _native_format(view) != expected_format or view.itemsize != _item_size(
+        info.dtype
+    ):
+        raise TypeError(
+            f"expected a buffer with format {expected_format!r} for {info.dtype.name.lower()}"
+        )
+
+    shape = tuple(view.shape or ())
+    if shape != info.shape and shape != (info.element_count,):
+        raise ValueError(f"expected source shape {info.shape}, received {shape}")
+    return view
+
+
+def _logical_bytes(info: TensorInfo, values: object) -> bytes:
+    view = _buffer_view(info, values)
+    if view is not None:
+        return view.tobytes(order="C")
+
+    try:
+        materialized = tuple(cast(Iterable[object], values))
+    except TypeError as error:
+        raise TypeError(
+            "source must be a buffer or an iterable of scalar values"
+        ) from error
+    if len(materialized) != info.element_count:
+        message = (
+            f"expected {info.element_count} elements for shape {info.shape}; "
+            f"received {len(materialized)}"
+        )
+        raise ValueError(message)
+    return struct.pack(f"={info.element_count}{_format(info.dtype)}", *materialized)
+
+
+def _writable_pointer(
+    view: memoryview,
+) -> tuple[ctypes.c_ubyte, ctypes.c_void_p] | None:
+    if view.readonly or not view.c_contiguous or view.nbytes == 0:
+        return None
+    anchor = ctypes.c_ubyte.from_buffer(view)
+    return anchor, ctypes.c_void_p(ctypes.addressof(anchor))
+
+
+def _contiguous_strides(shape: tuple[int, ...]) -> tuple[int, ...]:
+    strides = [0] * len(shape)
+    stride = 1
+    for axis in range(len(shape) - 1, -1, -1):
+        strides[axis] = stride
+        stride *= shape[axis]
+    return tuple(strides)
+
+
+def _physical_buffer_matches(info: TensorInfo, view: memoryview) -> bool:
+    if info.offset != 0 or not view.c_contiguous:
+        return False
+    if view.itemsize == 1 and _native_format(view) in {"b", "B", "c"}:
+        return (
+            view.ndim == 1
+            and view.nbytes == info.byte_count
+            and info.strides == _contiguous_strides(info.shape)
+        )
+    expected_strides = tuple(stride * view.itemsize for stride in info.strides)
+    return (
+        tuple(view.shape or ()) == info.shape
+        and tuple(view.strides or ()) == expected_strides
+    )
+
+
+def _pack_bound(info: TensorInfo, logical: bytes) -> bytes:
+    logical_values = _decode(info.dtype, info.byte_count, logical)
+    physical_values: list[float | int | bool] = [0] * info.element_count
+    for linear_index, value in enumerate(logical_values):
+        remaining = linear_index
+        physical_index = info.offset
+        for axis in range(len(info.shape) - 1, -1, -1):
+            coordinate = remaining % info.shape[axis]
+            remaining //= info.shape[axis]
+            physical_index += coordinate * info.strides[axis]
+        if physical_index < 0 or physical_index >= info.element_count:
+            raise ValueError("bound source layout exceeds its ABI storage extent")
+        physical_values[physical_index] = value
+    return struct.pack(
+        f"={info.element_count}{_format(info.dtype)}",
+        *physical_values,
+    )
+
+
+def _aligned_storage(
+    size: int,
+    alignment: int,
+) -> tuple[ctypes.Array[ctypes.c_ubyte], ctypes.c_void_p]:
+    if alignment <= 0 or alignment & (alignment - 1):
+        raise RuntimeError(f"invalid runtime alignment: {alignment}")
+    allocation = (ctypes.c_ubyte * (size + alignment - 1))()
+    address = (ctypes.addressof(allocation) + alignment - 1) & -alignment
+    return allocation, ctypes.c_void_p(address)
+
+
+@final
+class Runtime:
+    def __init__(self, path: str | PathLike[str]) -> None:
+        self._library: Library = load_library(str(Path(path).expanduser().resolve()))
+        self.structural_fingerprint: int = (
+            self._library.zgc_executable_structural_fingerprint()
+        )
+        self.runtime_size: int = self._library.zgc_runtime_size()
+        self.runtime_alignment: int = self._library.zgc_runtime_alignment()
+        self.mutable_bytes: int = self._library.zgc_runtime_mutable_bytes()
+        self._allocation, self._runtime = _aligned_storage(
+            self.runtime_size, self.runtime_alignment
+        )
+        self._closed = False
+        self._bound_storage: dict[int, object] = {}
+        require_ok(
+            self._library.zgc_runtime_init(self._runtime, self.runtime_size),
+            "zgc_runtime_init",
+        )
+        self.sources = self._read_sources()
+        self.outputs = self._read_outputs()
+        self._sources_by_name = {source.name: source for source in self.sources}
+
+    def _read_sources(self) -> tuple[Source, ...]:
+        sources: list[Source] = []
+        for index in range(self._library.zgc_executable_source_count()):
+            descriptor = SourceDescriptor()
+            require_ok(
+                self._library.zgc_executable_get_source_descriptor(
+                    index, ctypes.byref(descriptor)
+                ),
+                "zgc_executable_get_source_descriptor",
+            )
+            fields = cast(_SourceDescriptorFields, cast(object, descriptor))
+            sources.append(
+                Source(
+                    key=fields.key,
+                    name=fields.name.decode() if fields.name is not None else "",
+                    kind=SourceKind(fields.kind),
+                    binding=SourceBinding(fields.binding),
+                    tensor=_tensor_info(fields.tensor),
+                )
+            )
+        return tuple(sources)
+
+    def _read_outputs(self) -> tuple[TensorInfo, ...]:
+        outputs: list[TensorInfo] = []
+        for index in range(self._library.zgc_executable_output_count()):
+            descriptor = TensorDescriptor()
+            require_ok(
+                self._library.zgc_executable_get_output_descriptor(
+                    index, ctypes.byref(descriptor)
+                ),
+                "zgc_executable_get_output_descriptor",
+            )
+            outputs.append(_tensor_info(descriptor))
+        return tuple(outputs)
+
+    def set_source(
+        self,
+        name: str,
+        values: object,
+    ) -> None:
+        """Copy logical source values into storage owned by the runtime.
+
+        ``values`` may implement the Python buffer protocol or be an iterable
+        of scalar values. For a compiled bound source, the values are packed
+        into retained internal storage. Later changes to ``values`` therefore
+        cannot affect the runtime. Use :meth:`bind` to explicitly share caller
+        storage without copying.
+        """
+        self._require_open()
+        try:
+            source = self._sources_by_name[name]
+        except KeyError as error:
+            raise KeyError(f"unknown runtime source {name!r}") from error
+        if source.binding is SourceBinding.EMBEDDED:
+            raise ValueError(f"source {name!r} is embedded and cannot be replaced")
+
+        if source.binding is SourceBinding.BOUND:
+            payload = _pack_bound(
+                source.tensor,
+                _logical_bytes(source.tensor, values),
+            )
+            storage = bytearray(payload)
+            storage_view = memoryview(storage)
+            address = _writable_pointer(storage_view)
+            if address is None:
+                raise ValueError("cannot bind empty source storage")
+            anchor, pointer = address
+            require_ok(
+                self._library.zgc_runtime_bind_source(
+                    self._runtime,
+                    source.key,
+                    pointer,
+                    len(storage),
+                ),
+                "zgc_runtime_bind_source",
+            )
+            self._bound_storage[source.key] = (storage, storage_view, anchor)
+            return
+
+        view = _buffer_view(source.tensor, values)
+        direct = _writable_pointer(view) if view is not None else None
+        if direct is not None and view is not None and view.c_contiguous:
+            anchor, pointer = direct
+            byte_count = view.nbytes
+            keepalive: object = (values, view, anchor)
+        else:
+            payload = _logical_bytes(source.tensor, values)
+            pointer = ctypes.cast(ctypes.c_char_p(payload), ctypes.c_void_p)
+            byte_count = len(payload)
+            keepalive = payload
+        require_ok(
+            self._library.zgc_runtime_copy_source(
+                self._runtime,
+                source.key,
+                pointer,
+                byte_count,
+            ),
+            "zgc_runtime_copy_source",
+        )
+        _ = keepalive
+
+    def bind(self, name: str, values: object) -> None:
+        """Bind caller-owned physical storage without copying.
+
+        ``values`` must export a writable, contiguous buffer whose metadata exactly match the
+        compiled bound source. The runtime retains the buffer until the source
+        is rebound or the runtime is closed.
+        """
+        self._require_open()
+        try:
+            source = self._sources_by_name[name]
+        except KeyError as error:
+            raise KeyError(f"unknown runtime source {name!r}") from error
+        if source.binding is not SourceBinding.BOUND:
+            raise ValueError(f"source {name!r} is not a bound source")
+
+        view = _buffer_view(source.tensor, values)
+        if view is None:
+            raise TypeError("bound sources require an object exporting a buffer")
+        if not _physical_buffer_matches(source.tensor, view):
+            raise ValueError("buffer does not match the compiled source layout")
+        address = _writable_pointer(view)
+        if address is None:
+            raise ValueError("zero-copy binding requires a writable contiguous buffer")
+        anchor, pointer = address
+        require_ok(
+            self._library.zgc_runtime_bind_source(
+                self._runtime,
+                source.key,
+                pointer,
+                view.nbytes,
+            ),
+            "zgc_runtime_bind_source",
+        )
+        self._bound_storage[source.key] = (values, view, anchor)
+
+    def run(self, **sources: object) -> tuple[Tensor, ...]:
+        self._require_open()
+        for name, values in sources.items():
+            self.set_source(name, values)
+        require_ok(self._library.zgc_runtime_run(self._runtime), "zgc_runtime_run")
+        return tuple(self.output(index) for index in range(len(self.outputs)))
+
+    def output(self, index: int) -> Tensor:
+        """Copied output from the runtime."""
+        self._require_open()
+        if index < 0:
+            raise IndexError(f"runtime has no output {index}")
+        try:
+            info = self.outputs[index]
+        except IndexError as error:
+            raise IndexError(f"runtime has no output {index}") from error
+        storage = bytearray(info.byte_count)
+        view = memoryview(storage)
+        address = _writable_pointer(view)
+        if address is None:
+            raise ValueError("cannot create empty output storage")
+        anchor, pointer = address
+        require_ok(
+            self._library.zgc_runtime_copy_output(
+                self._runtime,
+                index,
+                pointer,
+                info.byte_count,
+            ),
+            "zgc_runtime_copy_output",
+        )
+        _ = anchor
+        return Tensor(info.dtype, info.shape, storage)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._library.zgc_runtime_deinit(self._runtime)
+        self._bound_storage.clear()
+        self._closed = True
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("runtime is closed")
+
+    def __enter__(self) -> Self:
+        self._require_open()
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        if hasattr(self, "_closed"):
+            self.close()
+
+
+def load(path: str | PathLike[str]) -> Runtime:
+    """Load a pre-compiled runtime from a local path."""
+    return Runtime(path)

zgc_runtime-0.1.0/src/zgc_runtime.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: zgc-runtime
+Version: 0.1.0
+Summary: Python runtime for ZGC executable artifacts
+Requires-Python: >=3.10

zgc_runtime-0.1.0/src/zgc_runtime.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+src/zgc/__init__.py
+src/zgc/_abi.py
+src/zgc/py.typed
+src/zgc/runtime.py
+src/zgc_runtime.egg-info/PKG-INFO
+src/zgc_runtime.egg-info/SOURCES.txt
+src/zgc_runtime.egg-info/dependency_links.txt
+src/zgc_runtime.egg-info/top_level.txt
+tests/test_buffers.py

zgc_runtime-0.1.0/src/zgc_runtime.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zgc_runtime-0.1.0/src/zgc_runtime.egg-info/top_level.txt

@@ -0,0 +1 @@
+zgc

zgc_runtime-0.1.0/tests/test_buffers.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+# pyright: reportPrivateUsage=false
+import ctypes
+import struct
+import unittest
+from array import array
+from typing import final
+
+from zgc import Runtime, Source, SourceBinding, SourceKind, Tensor, TensorInfo, dtype
+
+
+@final
+class _Library:
+    copied_source: bytes = b""
+    bound_pointer: int = 0
+    bound_size: int = 0
+    output: bytes = struct.pack("=4f", 5.0, 6.0, 7.0, 8.0)
+
+    def zgc_runtime_copy_source(
+        self,
+        _runtime: ctypes.c_void_p,
+        _source_key: int,
+        data: ctypes.c_void_p,
+        size: int,
+    ) -> int:
+        self.copied_source = ctypes.string_at(data, size)
+        return 0
+
+    def zgc_runtime_bind_source(
+        self,
+        _runtime: ctypes.c_void_p,
+        _source_key: int,
+        data: ctypes.c_void_p,
+        size: int,
+    ) -> int:
+        self.bound_pointer = data.value or 0
+        self.bound_size = size
+        return 0
+
+    def zgc_runtime_copy_output(
+        self,
+        _runtime: ctypes.c_void_p,
+        _output_index: int,
+        destination: ctypes.c_void_p,
+        size: int,
+    ) -> int:
+        _result = ctypes.memmove(
+            destination,
+            self.output,
+            min(size, len(self.output)),
+        )
+        return 0
+
+    def zgc_runtime_deinit(self, _: ctypes.c_void_p) -> None:
+        pass
+
+
+def _runtime(binding: SourceBinding) -> tuple[Runtime, _Library]:
+    info = TensorInfo(dtype.f32, (2, 2), (2, 1), 4, 16, 0)
+    source = Source(0, "input", SourceKind.INPUT, binding, info)
+    library = _Library()
+    runtime = Runtime.__new__(Runtime)
+    runtime._library = library  # pyright: ignore[reportAttributeAccessIssue]
+    runtime._runtime = ctypes.c_void_p(1)
+    runtime._closed = False
+    runtime._bound_storage = {}
+    runtime._sources_by_name = {"input": source}
+    runtime.outputs = (info,)
+    return runtime, library
+
+
+class BufferTests(unittest.TestCase):
+    def test_list_source_uses_scalar_fallback(self) -> None:
+        runtime, library = _runtime(SourceBinding.OWNED)
+        runtime.set_source("input", [1.0, 2.0, 3.0, 4.0])
+        self.assertEqual(library.copied_source, struct.pack("=4f", 1, 2, 3, 4))
+
+    def test_array_source_uses_buffer_contents(self) -> None:
+        runtime, library = _runtime(SourceBinding.OWNED)
+        values = array("f", [1.0, 2.0, 3.0, 4.0])
+        runtime.set_source("input", values)
+        self.assertEqual(library.copied_source, values.tobytes())
+
+    def test_bound_array_remains_borrowed(self) -> None:
+        runtime, library = _runtime(SourceBinding.BOUND)
+        values = array("f", [1.0, 2.0, 3.0, 4.0])
+        shaped = memoryview(values).cast("B").cast("f", shape=[2, 2])
+        runtime.bind("input", shaped)
+        values[0] = 9.0
+        payload = ctypes.string_at(library.bound_pointer, library.bound_size)
+        self.assertEqual(payload, values.tobytes())
+
+    def test_set_source_copies_bound_values(self) -> None:
+        runtime, library = _runtime(SourceBinding.BOUND)
+        values = array("f", [1.0, 2.0, 3.0, 4.0])
+        runtime.set_source("input", values)
+        values[0] = 9.0
+        payload = ctypes.string_at(library.bound_pointer, library.bound_size)
+        self.assertEqual(payload, struct.pack("=4f", 1.0, 2.0, 3.0, 4.0))
+
+    def test_output_owns_a_shaped_buffer(self) -> None:
+        runtime, _ = _runtime(SourceBinding.OWNED)
+        output = runtime.output(0)
+        self.assertIsInstance(output, Tensor)
+        self.assertEqual(output.buffer.format, "f")
+        self.assertEqual(output.buffer.shape, (2, 2))
+        self.assertEqual(output.strides, (8, 4))
+        self.assertEqual(output.tolist(), [5.0, 6.0, 7.0, 8.0])
+
+
+if __name__ == "__main__":
+    _ = unittest.main()