provium 0.1.0__py3-none-any.whl

provium/__init__.py

@@ -0,0 +1,45 @@
+from importlib.metadata import version
+
+from .artifact import Artifact, open_artifact
+from .catalog import ArtifactCatalog, ArtifactRegistration
+from .config import ConfigCodec, ConfigurationSnapshot, JsonValue
+from .discovery import discover_catalogs, reset_discovery
+from .header import ArtifactHeader, decode_header, encode_header
+from .procedure import ExecutionContext, Procedure, current_execution
+from .provenance import (
+    ArtifactLineage,
+    ArtifactRecord,
+    ArtifactReference,
+    ProcedureExecutionRecord,
+    ProcedureRecord,
+)
+from .reader import ArtifactReader
+from .writer import ArtifactWriter
+
+__version__ = version("provium")
+
+__all__ = [
+    "Artifact",
+    "ArtifactCatalog",
+    "ArtifactHeader",
+    "ArtifactLineage",
+    "ArtifactReader",
+    "ArtifactRecord",
+    "ArtifactReference",
+    "ArtifactRegistration",
+    "ArtifactWriter",
+    "ConfigCodec",
+    "ConfigurationSnapshot",
+    "ExecutionContext",
+    "JsonValue",
+    "Procedure",
+    "ProcedureExecutionRecord",
+    "ProcedureRecord",
+    "__version__",
+    "decode_header",
+    "discover_catalogs",
+    "encode_header",
+    "current_execution",
+    "open_artifact",
+    "reset_discovery",
+]

provium/artifact.py

@@ -0,0 +1,125 @@
+"""Generic typed artifact definitions and lazy provider resolution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from os import PathLike
+from typing import Any, ClassVar, cast, overload
+
+from .context import current_context
+from .reader import ArtifactReader
+from .writer import ArtifactWriter
+
+
+class Artifact[ReaderT: ArtifactReader, WriterT: ArtifactWriter]:
+    """Bind a logical artifact type to its concrete reader and writer types."""
+
+    reader: type[ReaderT] | Callable[[], type[ReaderT]]
+    writer: type[WriterT] | Callable[[], type[WriterT]]
+    _reader_type_cache: ClassVar[type[ArtifactReader] | None] = None
+    _writer_type_cache: ClassVar[type[ArtifactWriter] | None] = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._reader_type_cache = None
+        cls._writer_type_cache = None
+
+    @classmethod
+    def _resolve_reader(cls) -> type[ReaderT]:
+        cached = cls._reader_type_cache
+        if cached is not None:
+            return cast(type[ReaderT], cached)
+        provider = getattr(cls, "reader", None)
+        candidate = (
+            provider
+            if isinstance(provider, type)
+            else provider()
+            if callable(provider)
+            else None
+        )
+        if not isinstance(candidate, type) or not issubclass(candidate, ArtifactReader):
+            raise TypeError("reader provider must resolve to an ArtifactReader type")
+        cls._reader_type_cache = candidate
+        return cast(type[ReaderT], candidate)
+
+    @classmethod
+    def _resolve_writer(cls) -> type[WriterT]:
+        cached = cls._writer_type_cache
+        if cached is not None:
+            return cast(type[WriterT], cached)
+        provider = getattr(cls, "writer", None)
+        candidate = (
+            provider
+            if isinstance(provider, type)
+            else provider()
+            if callable(provider)
+            else None
+        )
+        if not isinstance(candidate, type) or not issubclass(candidate, ArtifactWriter):
+            raise TypeError("writer provider must resolve to an ArtifactWriter type")
+        cls._writer_type_cache = candidate
+        return cast(type[WriterT], candidate)
+
+    @classmethod
+    def open(cls, path: str | PathLike[str]) -> ReaderT:
+        context = current_context()
+        if context is None:
+            raise RuntimeError("artifact I/O requires an active execution context")
+        opener = getattr(context, "open_artifact", None)
+        if not callable(opener):
+            raise TypeError("active context does not support artifact opening")
+        return cast(ReaderT, opener(cls, path, cls._resolve_reader()))
+
+    @classmethod
+    def create(cls, path: str | PathLike[str]) -> WriterT:
+        context = current_context()
+        if context is None:
+            raise RuntimeError("artifact I/O requires an active execution context")
+        creator = getattr(context, "create_artifact", None)
+        if not callable(creator):
+            raise TypeError("active context does not support artifact creating")
+        return cast(WriterT, creator(cls, path, cls._resolve_writer()))
+
+
+__all__ = ["Artifact"]
+
+
+@overload
+def open_artifact(path: str | PathLike[str]) -> ArtifactReader: ...
+
+
+@overload
+def open_artifact[ReaderT: ArtifactReader, WriterT: ArtifactWriter](
+    path: str | PathLike[str],
+    *,
+    expected: type[Artifact[ReaderT, WriterT]],
+) -> ReaderT: ...
+
+
+@overload
+def open_artifact(
+    path: str | PathLike[str],
+    *,
+    expected: tuple[type[Artifact], ...],
+) -> ArtifactReader: ...
+
+
+def open_artifact(
+    path: str | PathLike[str],
+    *,
+    expected: type[Artifact] | tuple[type[Artifact], ...] | None = None,
+) -> ArtifactReader:
+    """Open an artifact whose concrete type will be discovered from its header."""
+    context = current_context()
+    if context is None:
+        raise RuntimeError("artifact I/O requires an active execution context")
+    opener = getattr(context, "open_unknown_artifact", None)
+    if not callable(opener):
+        raise TypeError("active context does not support artifact opening")
+    expected_types = None
+    if expected is not None:
+        expected_types = expected if isinstance(expected, tuple) else (expected,)
+    return cast(ArtifactReader, opener(path, expected_types))
+
+
+__all__.append("open_artifact")

provium/catalog.py

@@ -0,0 +1,80 @@
+"""Explicit registration of artifact classes and their persistent identifiers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from .artifact import Artifact
+
+
+def _require_identifier(value: str, field_name: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{field_name} must be a non-empty string")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactRegistration:
+    canonical_identifier: str
+    artifact: type[Artifact]
+    aliases: tuple[str, ...] = ()
+
+
+class ArtifactCatalog:
+    """Map canonical identifiers and aliases to typed artifact definitions."""
+
+    def __init__(self) -> None:
+        self._identifiers: dict[str, ArtifactRegistration] = {}
+        self._artifacts: dict[type[Artifact], ArtifactRegistration] = {}
+
+    def register(
+        self,
+        canonical_identifier: str,
+        artifact: type[Artifact],
+        *,
+        aliases: tuple[str, ...] = (),
+    ) -> ArtifactRegistration:
+        _require_identifier(canonical_identifier, "canonical identifier")
+        if not isinstance(artifact, type) or not issubclass(artifact, Artifact):
+            raise TypeError("artifact must be an Artifact class")
+        for alias in aliases:
+            _require_identifier(alias, "alias")
+        if len(aliases) != len(set(aliases)):
+            raise ValueError("duplicate alias in registration")
+        if canonical_identifier in aliases:
+            raise ValueError("alias must differ from the canonical identifier")
+        if canonical_identifier in self._identifiers:
+            raise ValueError(
+                f"canonical identifier is already registered: {canonical_identifier}"
+            )
+        if artifact in self._artifacts:
+            raise ValueError("artifact class is already registered")
+        for alias in aliases:
+            if alias in self._identifiers:
+                raise ValueError(f"alias is already registered: {alias}")
+
+        registration = ArtifactRegistration(canonical_identifier, artifact, aliases)
+        self._identifiers[canonical_identifier] = registration
+        self._identifiers.update((alias, registration) for alias in aliases)
+        self._artifacts[artifact] = registration
+        return registration
+
+    def resolve(self, identifier: str) -> ArtifactRegistration:
+        return self._identifiers[identifier]
+
+    def registration_for(self, artifact: type[Artifact]) -> ArtifactRegistration:
+        return self._artifacts[artifact]
+
+    @property
+    def registrations(self) -> Mapping[str, ArtifactRegistration]:
+        """Canonical registrations keyed by canonical identifier."""
+        return MappingProxyType(
+            {
+                registration.canonical_identifier: registration
+                for registration in self._artifacts.values()
+            }
+        )
+
+
+__all__ = ["ArtifactCatalog", "ArtifactRegistration"]

provium/config.py

@@ -0,0 +1,90 @@
+"""Typed, dependency-free procedure configuration serialization."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from typing import Protocol
+
+type JsonScalar = None | bool | int | float | str
+type JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]
+
+
+class ConfigCodec[ConfigT](Protocol):
+    """Encode and decode one procedure configuration type."""
+
+    identifier: str
+
+    def encode(self, config: ConfigT) -> JsonValue: ...
+
+    def decode(self, value: JsonValue) -> ConfigT: ...
+
+
+def _canonical_json_value(value: object) -> JsonValue:
+    """Validate a JSON value and return an independent normalized copy."""
+    _validate_json_value(value)
+    encoded = json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+    decoded: JsonValue = json.loads(encoded)
+    return decoded
+
+
+def _validate_json_value(value: object) -> None:
+    if value is None or isinstance(value, (bool, int, str)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError("configuration must contain finite JSON numbers")
+        return
+    if isinstance(value, list):
+        for item in value:
+            _validate_json_value(item)
+        return
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) for key in value):
+            raise TypeError("configuration JSON object keys must be strings")
+        for item in value.values():
+            _validate_json_value(item)
+        return
+    raise TypeError("configuration must be a JSON value")
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationSnapshot:
+    """A JSON-compatible configuration value paired with its codec identity."""
+
+    codec_identifier: str
+    value: JsonValue
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.codec_identifier, str) or not self.codec_identifier:
+            raise ValueError("codec_identifier must be a non-empty string")
+        object.__setattr__(self, "value", _canonical_json_value(self.value))
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {"codec_identifier": self.codec_identifier, "value": self.value},
+            allow_nan=False,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> ConfigurationSnapshot:
+        decoded = json.loads(value)
+        if not isinstance(decoded, dict) or set(decoded) != {
+            "codec_identifier",
+            "value",
+        }:
+            raise ValueError("invalid configuration snapshot")
+        return cls(decoded["codec_identifier"], decoded["value"])
+
+
+__all__ = ["ConfigCodec", "ConfigurationSnapshot", "JsonValue"]

provium/context.py

@@ -0,0 +1,40 @@
+"""Logical execution-context state shared by context-bound resources."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+_active_context: ContextVar[object | None] = ContextVar(
+    "provium_active_execution_context",
+    default=None,
+)
+
+
+def current_context() -> object | None:
+    """Return the active execution-context owner in this logical context."""
+    return _active_context.get()
+
+
+def set_context(owner: object) -> Token[object | None]:
+    """Set the active owner and return the token required to restore it."""
+    return _active_context.set(owner)
+
+
+def reset_context(token: Token[object | None]) -> None:
+    """Restore the logical context represented by a prior token."""
+    _active_context.reset(token)
+
+
+@contextmanager
+def activate_context(owner: object) -> Generator[None]:
+    """Activate an owner temporarily, restoring the previous owner on exit."""
+    token = set_context(owner)
+    try:
+        yield
+    finally:
+        reset_context(token)
+
+
+__all__ = ["activate_context", "current_context", "reset_context", "set_context"]

provium/discovery.py

@@ -0,0 +1,44 @@
+"""Discover explicitly published artifact catalogs through package entry points."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+from .catalog import ArtifactCatalog
+
+ENTRY_POINT_GROUP = "provium.catalogs"
+_discovered_catalog: ArtifactCatalog | None = None
+
+
+def discover_catalogs() -> ArtifactCatalog:
+    """Load and combine installed catalogs, caching a successful discovery."""
+    global _discovered_catalog
+    if _discovered_catalog is not None:
+        return _discovered_catalog
+
+    discovered = ArtifactCatalog()
+    for entry_point in metadata.entry_points().select(group=ENTRY_POINT_GROUP):
+        catalog = entry_point.load()
+        if not isinstance(catalog, ArtifactCatalog):
+            message = (
+                f"catalog entry point {entry_point.name!r} must expose "
+                "an ArtifactCatalog"
+            )
+            raise TypeError(message)
+        for registration in catalog.registrations.values():
+            discovered.register(
+                registration.canonical_identifier,
+                registration.artifact,
+                aliases=registration.aliases,
+            )
+    _discovered_catalog = discovered
+    return discovered
+
+
+def reset_discovery() -> None:
+    """Clear cached discovery state, primarily for isolated tests."""
+    global _discovered_catalog
+    _discovered_catalog = None
+
+
+__all__ = ["discover_catalogs", "reset_discovery"]

provium/header.py

@@ -0,0 +1,148 @@
+"""Binary container prefix and deterministic artifact metadata encoding."""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+from .provenance import ArtifactLineage
+
+MAGIC = b"PROVIUM\0"
+CONTAINER_VERSION = 1
+_PREFIX = struct.Struct(">8sHQQ")
+PREFIX_SIZE = _PREFIX.size
+_METADATA_KEYS = {
+    "artifact_identifier",
+    "artifact_identity",
+    "body_offset",
+    "body_length",
+    "body_digest",
+    "lineage",
+}
+
+
+def _require_text(value: str, field_name: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{field_name} must be a non-empty string")
+
+
+def _metadata_bytes(header: ArtifactHeader) -> bytes:
+    return json.dumps(
+        {
+            "artifact_identifier": header.artifact_identifier,
+            "artifact_identity": header.artifact_identity,
+            "body_digest": header.body_digest,
+            "body_length": header.body_length,
+            "body_offset": header.body_offset,
+            "lineage": header.lineage.to_dict(),
+        },
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactHeader:
+    """The generic metadata required to locate and identify an artifact body."""
+
+    artifact_identifier: str
+    artifact_identity: str
+    body_offset: int
+    body_length: int
+    body_digest: str
+    lineage: ArtifactLineage
+    metadata_offset: int = PREFIX_SIZE
+    metadata_length: int = field(init=False)
+
+    def __post_init__(self) -> None:
+        _require_text(self.artifact_identifier, "artifact_identifier")
+        _require_text(self.artifact_identity, "artifact_identity")
+        if not isinstance(self.body_offset, int) or self.body_offset < 0:
+            raise ValueError("body_offset must be a non-negative integer")
+        if not isinstance(self.body_length, int) or self.body_length < 0:
+            raise ValueError("body_length must be a non-negative integer")
+        _require_text(self.body_digest, "body_digest")
+        if not isinstance(self.lineage, ArtifactLineage):
+            raise TypeError("lineage must be an ArtifactLineage")
+        if (
+            not isinstance(self.metadata_offset, int)
+            or self.metadata_offset < PREFIX_SIZE
+        ):
+            raise ValueError("metadata_offset must not overlap the fixed header")
+        object.__setattr__(self, "metadata_length", len(_metadata_bytes(self)))
+
+
+def encode_header(header: ArtifactHeader) -> bytes:
+    """Encode a complete fixed prefix and its canonical metadata."""
+    if not isinstance(header, ArtifactHeader):
+        raise TypeError("header must be an ArtifactHeader")
+    metadata = _metadata_bytes(header)
+    prefix = _PREFIX.pack(
+        MAGIC,
+        CONTAINER_VERSION,
+        header.metadata_offset,
+        len(metadata),
+    )
+    padding = bytes(header.metadata_offset - PREFIX_SIZE)
+    return prefix + padding + metadata
+
+
+def _decode_metadata(metadata_bytes: bytes, metadata_offset: int) -> ArtifactHeader:
+    metadata: Any = json.loads(metadata_bytes.decode("utf-8"))
+    if not isinstance(metadata, dict) or set(metadata) != _METADATA_KEYS:
+        raise ValueError("invalid metadata shape")
+    return ArtifactHeader(
+        artifact_identifier=metadata["artifact_identifier"],
+        artifact_identity=metadata["artifact_identity"],
+        body_offset=metadata["body_offset"],
+        body_length=metadata["body_length"],
+        body_digest=metadata["body_digest"],
+        lineage=ArtifactLineage.from_dict(metadata["lineage"]),
+        metadata_offset=metadata_offset,
+    )
+
+
+def decode_header(data: bytes | bytearray | memoryview) -> ArtifactHeader:
+    """Decode and validate a complete artifact header from bytes."""
+    if len(data) < PREFIX_SIZE:
+        raise ValueError("truncated fixed header")
+    magic, version, metadata_offset, metadata_length = _PREFIX.unpack_from(data)
+    if magic != MAGIC:
+        raise ValueError("invalid artifact magic bytes")
+    if version != CONTAINER_VERSION:
+        raise ValueError(f"unsupported container version: {version}")
+    if metadata_offset < PREFIX_SIZE:
+        raise ValueError("metadata offset overlaps the fixed header")
+    metadata_end = metadata_offset + metadata_length
+    if len(data) < metadata_end:
+        raise ValueError("truncated metadata")
+    metadata_bytes = bytes(data[metadata_offset:metadata_end])
+    try:
+        header = _decode_metadata(metadata_bytes, metadata_offset)
+    except (
+        KeyError,
+        TypeError,
+        UnicodeDecodeError,
+        json.JSONDecodeError,
+        ValueError,
+    ) as error:
+        raise ValueError("malformed artifact metadata") from error
+    if (
+        metadata_offset != header.metadata_offset
+        or metadata_length != header.metadata_length
+    ):
+        raise ValueError("malformed artifact metadata encoding")
+    return header
+
+
+__all__ = [
+    "CONTAINER_VERSION",
+    "MAGIC",
+    "PREFIX_SIZE",
+    "ArtifactHeader",
+    "decode_header",
+    "encode_header",
+]