protoloom 0.1.4__py3-none-any.whl

protoloom/__init__.py

@@ -0,0 +1,22 @@
+from protoloom.model import (
+    Confidence,
+    EnumType,
+    EnumValue,
+    Evidence,
+    Field,
+    Message,
+    RecoveredSchema,
+)
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "Confidence",
+    "EnumType",
+    "EnumValue",
+    "Evidence",
+    "Field",
+    "Message",
+    "RecoveredSchema",
+    "__version__",
+]

protoloom/bench/__init__.py

@@ -0,0 +1,27 @@
+from protoloom.bench.metrics import (
+    METRIC_NAMES,
+    AggregateReport,
+    BenchmarkEnum,
+    BenchmarkField,
+    BenchmarkMessage,
+    BenchmarkSchema,
+    MetricReport,
+    Score,
+    aggregate_reports,
+    score_target,
+    type_fidelity_ceiling,
+)
+
+__all__ = [
+    "METRIC_NAMES",
+    "AggregateReport",
+    "BenchmarkEnum",
+    "BenchmarkField",
+    "BenchmarkMessage",
+    "BenchmarkSchema",
+    "MetricReport",
+    "Score",
+    "aggregate_reports",
+    "score_target",
+    "type_fidelity_ceiling",
+]

protoloom/bench/corpus.py

@@ -0,0 +1,332 @@
+import hashlib
+import itertools
+import os
+import stat
+import tempfile
+import unicodedata
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from math import prod
+from pathlib import Path
+from typing import Any, BinaryIO, cast
+from urllib.parse import urlparse
+
+from protoloom.bench.jsonio import read_json
+
+
+class CorpusError(ValueError):
+    pass
+
+
+MAX_CORPUS_NAME_BYTES = 255
+MAX_CORPUS_ARTIFACT_SIZE = 1024 * 1024 * 1024
+MAX_MATRIX_AXES = 32
+MAX_COMPILATION_JOBS = 100_000
+
+
+def _https_url(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme != "https" or not parsed.netloc or parsed.username is not None:
+        raise CorpusError(f"artifact URL must be unauthenticated HTTPS: {value}")
+    return value
+
+
+def _validate_name(name: str, label: str) -> None:
+    if (
+        name in {"", ".", ".."}
+        or Path(name).name != name
+        or len(name.encode("utf-8")) > MAX_CORPUS_NAME_BYTES
+        or any(unicodedata.category(character).startswith("C") for character in name)
+    ):
+        raise CorpusError(f"{label} name is unsafe")
+
+
+@dataclass(frozen=True, slots=True)
+class Artifact:
+    name: str
+    sha256: str
+    path: str | None = None
+    url: str | None = None
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name, "artifact")
+        if (self.path is None) == (self.url is None):
+            raise CorpusError(f"artifact {self.name!r} needs exactly one source")
+        if len(self.sha256) != 64 or any(
+            character not in "0123456789abcdef" for character in self.sha256
+        ):
+            raise CorpusError(f"artifact {self.name!r} has an invalid SHA-256")
+        if self.url is not None:
+            _https_url(self.url)
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusTarget:
+    name: str
+    truth: Artifact
+    recovered: Artifact
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name, "target")
+        if self.truth.name == self.recovered.name:
+            raise CorpusError(f"target {self.name!r} has duplicate artifact names")
+
+
+@dataclass(frozen=True, slots=True)
+class CompilationJob:
+    target: CorpusTarget
+    variant: Mapping[str, str]
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusManifest:
+    name: str
+    targets: tuple[CorpusTarget, ...]
+    matrix: Mapping[str, tuple[str, ...]]
+    root: Path
+
+    def __post_init__(self) -> None:
+        _validate_name(self.name, "corpus")
+        if not self.targets:
+            raise CorpusError("manifest must contain at least one target")
+        if len({target.name for target in self.targets}) != len(self.targets):
+            raise CorpusError("target names must be unique")
+        if len(self.matrix) > MAX_MATRIX_AXES:
+            raise CorpusError(f"matrix contains more than {MAX_MATRIX_AXES} axes")
+        if any(not values for values in self.matrix.values()):
+            raise CorpusError("matrix axes cannot be empty")
+        if any(len(set(values)) != len(values) for values in self.matrix.values()):
+            raise CorpusError("matrix axis values must be unique")
+        jobs = len(self.targets) * prod(len(values) for values in self.matrix.values())
+        if jobs > MAX_COMPILATION_JOBS:
+            raise CorpusError(f"matrix expands beyond {MAX_COMPILATION_JOBS} jobs")
+
+    def variants(self) -> tuple[Mapping[str, str], ...]:
+        keys = tuple(self.matrix)
+        products = itertools.product(*(self.matrix[key] for key in keys))
+        return tuple(dict(zip(keys, values, strict=True)) for values in products)
+
+    def compilation_jobs(self) -> tuple[CompilationJob, ...]:
+        variants = self.variants()
+        return tuple(
+            CompilationJob(target, variant)
+            for target in self.targets
+            for variant in variants
+        )
+
+
+def drive_compilation_matrix(
+    manifest: CorpusManifest, build: Callable[[CompilationJob], None]
+) -> None:
+    for job in manifest.compilation_jobs():
+        build(job)
+
+
+def load_manifest(path: Path) -> CorpusManifest:
+    try:
+        raw = read_json(path)
+        if not isinstance(raw, dict):
+            raise CorpusError("manifest root must be an object")
+        _reject_unknown(raw, {"name", "targets", "matrix"}, "manifest")
+        targets = tuple(_target(item) for item in _list(raw, "targets"))
+        if not targets:
+            raise CorpusError("manifest must contain at least one target")
+        names = [target.name for target in targets]
+        if len(set(names)) != len(names):
+            raise CorpusError("target names must be unique")
+        matrix_raw = raw.get("matrix", {})
+        if not isinstance(matrix_raw, dict):
+            raise CorpusError("matrix must be an object")
+        matrix: dict[str, tuple[str, ...]] = {}
+        for key, values in matrix_raw.items():
+            axis = _safe_string(key, "matrix axis")
+            matrix[axis] = tuple(
+                _safe_string(value, "matrix value")
+                for value in _as_list(values, "matrix value")
+            )
+        if any(not values for values in matrix.values()):
+            raise CorpusError("matrix axes cannot be empty")
+        return CorpusManifest(
+            _string(raw["name"], "corpus name"),
+            targets,
+            matrix,
+            path.parent.resolve(),
+        )
+    except CorpusError:
+        raise
+    except (
+        KeyError,
+        TypeError,
+        ValueError,
+        UnicodeError,
+        OSError,
+        RecursionError,
+    ) as error:
+        raise CorpusError(f"invalid corpus manifest: {path}") from error
+
+
+def materialize(
+    manifest: CorpusManifest,
+    destination: Path,
+    *,
+    max_artifact_size: int = MAX_CORPUS_ARTIFACT_SIZE,
+) -> Mapping[str, Path]:
+    if max_artifact_size <= 0:
+        raise ValueError("maximum artifact size must be positive")
+    if destination.is_symlink():
+        raise CorpusError(f"corpus cache is a symlink: {destination}")
+    destination.mkdir(parents=True, exist_ok=True)
+    resolved: dict[str, Path] = {}
+    for target in manifest.targets:
+        target_root = destination / target.name
+        if target_root.is_symlink():
+            raise CorpusError(f"target cache is a symlink: {target_root}")
+        target_root.mkdir(parents=True, exist_ok=True)
+        for artifact in (target.truth, target.recovered):
+            key = f"{target.name}/{artifact.name}"
+            output = target_root / artifact.name
+            if output.is_symlink():
+                raise CorpusError(f"artifact cache is a symlink: {output}")
+            if (
+                not output.exists()
+                or sha256(output, max_artifact_size) != artifact.sha256
+            ):
+                _copy_artifact(manifest.root, artifact, output, max_artifact_size)
+            digest = sha256(output, max_artifact_size)
+            if digest != artifact.sha256:
+                output.unlink(missing_ok=True)
+                raise CorpusError(
+                    f"SHA-256 mismatch for {key}: expected "
+                    f"{artifact.sha256}, got {digest}"
+                )
+            resolved[key] = output
+    return resolved
+
+
+def sha256(path: Path, max_size: int = MAX_CORPUS_ARTIFACT_SIZE) -> str:
+    if max_size <= 0:
+        raise ValueError("maximum artifact size must be positive")
+    digest = hashlib.sha256()
+    total = 0
+    with path.open("rb") as stream:
+        _require_regular(stream, path)
+        if os.fstat(stream.fileno()).st_size > max_size:
+            raise CorpusError(f"artifact exceeds {max_size} bytes: {path}")
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            total += len(chunk)
+            if total > max_size:
+                raise CorpusError(f"artifact exceeds {max_size} bytes: {path}")
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _copy_artifact(root: Path, artifact: Artifact, output: Path, max_size: int) -> None:
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb", dir=output.parent, prefix=f".{output.name}.", delete=False
+        ) as writer:
+            temporary = Path(writer.name)
+            sink = cast(BinaryIO, writer)
+            if artifact.path is not None:
+                source = (root / artifact.path).resolve()
+                if not source.is_relative_to(root):
+                    raise CorpusError(
+                        f"artifact path escapes corpus root: {artifact.path}"
+                    )
+                with source.open("rb") as reader:
+                    _require_regular(reader, source)
+                    _copy_bounded(reader, sink, max_size)
+            else:
+                assert artifact.url is not None
+                with urllib.request.urlopen(artifact.url, timeout=30) as response:
+                    _https_url(response.geturl())
+                    _copy_bounded(response, sink, max_size)
+            writer.flush()
+            os.fsync(writer.fileno())
+        temporary.replace(output)
+        _sync_directory(output.parent)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def _sync_directory(path: Path) -> None:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    descriptor = os.open(path, flags)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _require_regular(stream: BinaryIO, path: Path) -> None:
+    if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+        raise CorpusError(f"artifact is not a regular file: {path}")
+
+
+def _copy_bounded(reader: BinaryIO, writer: BinaryIO, max_size: int) -> None:
+    copied = 0
+    while chunk := reader.read(min(1024 * 1024, max_size - copied + 1)):
+        copied += len(chunk)
+        if copied > max_size:
+            raise CorpusError(f"artifact exceeds {max_size} bytes")
+        writer.write(chunk)
+
+
+def _target(value: object) -> CorpusTarget:
+    if not isinstance(value, dict):
+        raise CorpusError("target must be an object")
+    _reject_unknown(value, {"name", "truth", "recovered"}, "target")
+    return CorpusTarget(
+        _string(value["name"], "target name"),
+        _artifact(_mapping(value["truth"], "truth")),
+        _artifact(_mapping(value["recovered"], "recovered")),
+    )
+
+
+def _artifact(value: Mapping[str, Any]) -> Artifact:
+    _reject_unknown(value, {"name", "sha256", "path", "url"}, "artifact")
+    return Artifact(
+        name=_string(value["name"], "artifact name"),
+        sha256=_string(value["sha256"], "artifact SHA-256"),
+        path=_string(value["path"], "artifact path") if "path" in value else None,
+        url=_string(value["url"], "artifact URL") if "url" in value else None,
+    )
+
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, dict):
+        raise CorpusError(f"{label} must be an object")
+    return value
+
+
+def _list(value: Mapping[str, Any], key: str) -> list[object]:
+    return _as_list(value[key], key)
+
+
+def _as_list(value: object, label: str) -> list[Any]:
+    if not isinstance(value, list):
+        raise CorpusError(f"{label} must be an array")
+    return value
+
+
+def _string(value: object, label: str) -> str:
+    if not isinstance(value, str):
+        raise CorpusError(f"{label} must be a string")
+    return value
+
+
+def _safe_string(value: object, label: str) -> str:
+    text = _string(value, label)
+    _validate_name(text, label)
+    return text
+
+
+def _reject_unknown(value: Mapping[str, Any], allowed: set[str], label: str) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise CorpusError(f"{label} has unknown field: {unknown[0]}")

protoloom/bench/jsonio.py

@@ -0,0 +1,60 @@
+import json
+import math
+import os
+import stat
+from pathlib import Path
+from typing import Any
+
+MAX_BENCH_JSON_SIZE = 16 * 1024 * 1024
+MAX_JSON_NUMBER_CHARACTERS = 1000
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def _reject_constant(value: str) -> None:
+    raise ValueError(f"non-finite JSON number: {value}")
+
+
+def _bounded_number(value: str) -> str:
+    if len(value) > MAX_JSON_NUMBER_CHARACTERS:
+        raise ValueError(f"JSON number exceeds {MAX_JSON_NUMBER_CHARACTERS} characters")
+    return value
+
+
+def _bounded_int(value: str) -> int:
+    return int(_bounded_number(value))
+
+
+def _finite_float(value: str) -> float:
+    result = float(_bounded_number(value))
+    if not math.isfinite(result):
+        raise ValueError(f"JSON number exceeds finite range: {value}")
+    return result
+
+
+def read_json(path: Path, max_size: int = MAX_BENCH_JSON_SIZE) -> Any:
+    if max_size <= 0:
+        raise ValueError("maximum JSON size must be positive")
+    with path.open("rb") as stream:
+        status = os.fstat(stream.fileno())
+        if not stat.S_ISREG(status.st_mode):
+            raise ValueError(f"JSON input is not a regular file: {path}")
+        if status.st_size > max_size:
+            raise ValueError(f"JSON input exceeds {max_size} bytes: {path}")
+        payload = stream.read(max_size + 1)
+    if len(payload) > max_size:
+        raise ValueError(f"JSON input exceeds {max_size} bytes: {path}")
+    return json.loads(
+        payload,
+        object_pairs_hook=_unique_object,
+        parse_constant=_reject_constant,
+        parse_float=_finite_float,
+        parse_int=_bounded_int,
+    )