metewand 0.2.0__py3-none-any.whl

metewand/__init__.py

@@ -0,0 +1,53 @@
+"""Small, process-based Python worker helpers for Metewand."""
+
+__version__ = "0.2.0"
+
+from ._artifacts import (
+    file_entry,
+    read_json,
+    write_dataset_manifest,
+    write_json,
+    write_metrics,
+    write_result,
+)
+from ._buffered import BufferedTrace, Decision
+from ._canonical import CanonicalJsonError, canonical_bytes, parse_json
+from ._worker import (
+    SDK_VERSION,
+    Evaluation,
+    Implementation,
+    OneShotImplementation,
+    BufferedImplementation,
+    ProtocolError,
+    WorkerError,
+    serve_dataset_materializer,
+    serve_evaluator,
+    serve_implementation,
+)
+
+from ._functions import FunctionContext, serve_function
+
+__all__ = [
+    "FunctionContext",
+    "serve_function",
+    "BufferedImplementation",
+    "BufferedTrace",
+    "Decision",
+    "CanonicalJsonError",
+    "Evaluation",
+    "Implementation",
+    "OneShotImplementation",
+    "ProtocolError",
+    "WorkerError",
+    "canonical_bytes",
+    "file_entry",
+    "parse_json",
+    "read_json",
+    "serve_dataset_materializer",
+    "serve_evaluator",
+    "serve_implementation",
+    "write_dataset_manifest",
+    "write_json",
+    "write_metrics",
+    "write_result",
+]

metewand/__main__.py

@@ -0,0 +1,9 @@
+"""Function worker entrypoint used by Metewand's local launcher."""
+
+import sys
+
+from ._functions import serve_function
+
+if len(sys.argv) != 4:
+    raise SystemExit("Usage: python -m metewand ROLE FILE FUNCTION")
+serve_function(*sys.argv[1:])

metewand/_artifacts.py

@@ -0,0 +1,157 @@
+"""Explicit file inventories and version-1 worker output envelopes."""
+
+import hashlib
+import re
+from pathlib import Path
+
+from ._canonical import MAX_SAFE_INTEGER, canonical_bytes, parse_json
+
+
+def read_json(path):
+    """Read a document using the restricted version-1 JSON domain."""
+    return parse_json(Path(path).read_bytes())
+
+
+def write_json(path, value):
+    """Write canonical JSON and close the file before returning."""
+    encoded = canonical_bytes(value)
+    Path(path).write_bytes(encoded)
+
+
+def _relative_path(value):
+    if not isinstance(value, (str, Path)):
+        raise TypeError("Paths must be strings or pathlib Paths.")
+    value = str(value)
+    if (
+        not value
+        or value.startswith("/")
+        or "\\" in value
+        or "\x00" in value
+        or any(part in {"", ".", ".."} for part in value.split("/"))
+    ):
+        raise ValueError(
+            "Paths must be normalized, nonempty, and relative to the assigned directory."
+        )
+    return value
+
+
+def _output_path(directory, relative):
+    relative = _relative_path(relative)
+    root = Path(directory).resolve()
+    target = root / relative
+    if not target.resolve().is_relative_to(root):
+        raise ValueError("Output paths must stay beneath the assigned directory.")
+    return target
+
+
+def _object(value, name):
+    if type(value) is not dict:
+        raise ValueError(f"{name} must be a JSON object.")
+    canonical_bytes(value)
+    return value
+
+
+def _representation(value):
+    _object(value, "File representation")
+    if not value or set(value) - {"shape", "data_type", "byte_order", "sparse_layout"}:
+        raise ValueError(
+            "File representation must contain only version-1 representation fields."
+        )
+    if "shape" in value and (
+        type(value["shape"]) is not list
+        or any(
+            type(size) is not int or not 0 <= size <= MAX_SAFE_INTEGER
+            for size in value["shape"]
+        )
+    ):
+        raise ValueError("Shape must contain nonnegative safe integers.")
+    for key in ("data_type", "sparse_layout"):
+        if key in value and (type(value[key]) is not str or not value[key]):
+            raise ValueError(f"{key} must be a nonempty string.")
+    if "byte_order" in value and (
+        type(value["byte_order"]) is not str
+        or value["byte_order"] not in {"little", "big", "not_applicable"}
+    ):
+        raise ValueError("Invalid byte order.")
+
+
+def file_entry(directory, path, media_type, *, representation=None):
+    """Hash a completed file and describe its author-supplied representation."""
+    path = _relative_path(path)
+    target = _output_path(directory, path)
+    if not target.is_file() or target.is_symlink():
+        raise ValueError("An inventory entry must identify a regular file.")
+    with target.open("rb") as source:
+        digest = hashlib.file_digest(source, "sha256").hexdigest()
+    entry = {
+        "path": path,
+        "media_type": media_type,
+        "sha256": digest,
+        "size_bytes": target.stat().st_size,
+    }
+    if representation is not None:
+        entry["representation"] = representation
+    _files([entry], manifest=None)
+    return entry
+
+
+def _files(files, manifest):
+    entries = list(files)
+    paths = set()
+    for entry in entries:
+        _object(entry, "File entry")
+        required = {"path", "media_type", "sha256", "size_bytes"}
+        if not required <= set(entry) or set(entry) - required - {"representation"}:
+            raise ValueError(
+                "File entries must contain the version-1 inventory fields."
+            )
+        if type(entry["path"]) is not str:
+            raise ValueError("File inventory paths must be strings.")
+        path = _relative_path(entry["path"])
+        if path in paths or path == manifest:
+            raise ValueError(
+                "File inventory paths must be unique and exclude the manifest itself."
+            )
+        paths.add(path)
+        if type(entry["media_type"]) is not str or not entry["media_type"]:
+            raise ValueError("Media types must be nonempty strings.")
+        if type(entry["sha256"]) is not str or not re.fullmatch(
+            "[0-9a-f]{64}", entry["sha256"]
+        ):
+            raise ValueError("File digests must be lowercase SHA-256 hex strings.")
+        size = entry["size_bytes"]
+        if type(size) is not int or not 0 <= size <= MAX_SAFE_INTEGER:
+            raise ValueError("File sizes must be nonnegative safe integers.")
+        if "representation" in entry:
+            _representation(entry["representation"])
+    return sorted(entries, key=lambda entry: entry["path"].encode("utf-8"))
+
+
+def write_dataset_manifest(directory, files, *, manifest="dataset-manifest.json"):
+    """Write a complete dataset inventory last and return its relative path."""
+    manifest = _relative_path(manifest)
+    document = {"schema_version": 1, "complete": True, "files": _files(files, manifest)}
+    write_json(_output_path(directory, manifest), document)
+    return manifest
+
+
+def write_result(directory, data, *, schema=None, files=(), manifest="result.json"):
+    """Write a problem-owned result envelope and return its relative manifest path."""
+    manifest = _relative_path(manifest)
+    document = {
+        "schema_version": 1,
+        "data": _object(data, "Result data"),
+        "files": _files(files, manifest),
+    }
+    if schema is not None:
+        document["schema"] = _relative_path(schema)
+    write_json(_output_path(directory, manifest), document)
+    return manifest
+
+
+def write_metrics(path, data, *, schema=None):
+    """Write evaluator-owned metrics at the exact path assigned by Metewand."""
+    document = {"schema_version": 1, "data": _object(data, "Metrics data")}
+    if schema is not None:
+        document["schema"] = _relative_path(schema)
+    write_json(path, document)

metewand/_buffered.py

@@ -0,0 +1,223 @@
+"""Bounded local observers; scientific formulas remain adapter-owned."""
+
+import hashlib
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._artifacts import _relative_path
+from ._canonical import MAX_SAFE_INTEGER, canonical_bytes, parse_json
+
+
+@dataclass(frozen=True)
+class Decision:
+    reason: str | None = None
+
+    @property
+    def stop(self):
+        return self.reason is not None
+
+    def __bool__(self):
+        return not self.stop
+
+
+def _fail(message, code="operation_failed"):
+    from ._worker import WorkerError
+    raise WorkerError(code, message)
+
+
+def _file(path, data):
+    return {"path": path, "sha256": hashlib.sha256(data).hexdigest(), "size_bytes": len(data)}
+
+
+class BufferedTrace:
+    """Freeze selected results and finish the checked terminal iterate before return.
+
+    ``clock`` returns cumulative monotonic nanoseconds from the declared scope's
+    origin. Native integrations can write to ``directory`` and adopt the same
+    artifact contract after their solve, with no per-point Python callbacks.
+    """
+
+    def __init__(self, profile, directory, *, clock=None):
+        self.profile = parse_json(canonical_bytes(profile))
+        self.policy = self.profile["policy"]
+        self.directory = Path(directory)
+        self.points = []
+        self.snapshots = []
+        self.data = []
+        self.reached = []
+        self.reason = None
+        self.finished = False
+        self.adopted = None
+        self.total = 0
+        self.trace_bytes = 0
+        self.snapshot_bytes = 0
+        for key in ("max-observations", "max-trace-points", "max-buffer-bytes", "terminal-reserve-bytes"):
+            value = self.policy[key]
+            if type(value) is not int or not 0 < value <= MAX_SAFE_INTEGER:
+                _fail(f"Invalid profile bound: {key}")
+        if self.policy["terminal-reserve-bytes"] > self.policy["max-buffer-bytes"]:
+            _fail("Terminal reserve exceeds buffer capacity.")
+        self.schedule = self.profile["check_schedule"]
+        self.schedule.setdefault("start", 0)
+        if type(self.schedule["every"]) is not int or not 0 < self.schedule["every"] <= MAX_SAFE_INTEGER:
+            _fail("Check interval must be a positive safe integer.")
+        self.thresholds = self.policy.get("record-thresholds") or ([self.policy["threshold"]] if "threshold" in self.policy else [])
+        expression = self.policy["max-active-time"].strip()
+        for suffix, multiplier in (("ms", 1_000_000), ("s", 1_000_000_000), ("min", 60_000_000_000), ("h", 3_600_000_000_000)):
+            if expression.endswith(suffix):
+                self.active_ns = int(expression[:-len(suffix)].strip()) * multiplier
+                break
+        else:
+            _fail("Invalid max-active-time.")
+        if not 0 < self.active_ns <= MAX_SAFE_INTEGER:
+            _fail("Invalid max-active-time.")
+        epoch = time.perf_counter_ns()
+        self.clock = clock if clock is not None else lambda: time.perf_counter_ns() - epoch
+
+    def _reaches(self, value, threshold):
+        return value <= threshold if self.policy["direction"] == "at_most" else value >= threshold
+
+    def observe(self, progress, measure, snapshot):
+        return self._check(progress, measure, snapshot, False)
+
+    def record(self, progress, metrics, snapshot):
+        return self._check(progress, lambda: metrics, snapshot, False)
+
+    def _snapshot(self, snapshot):
+        data = snapshot()
+        if type(data) is not dict:
+            _fail("Snapshot data must be a JSON object.")
+        return canonical_bytes({"schema_version": 1, "data": data, "files": []})
+
+    def _check(self, progress, measure, snapshot, terminal):
+        if self.finished or self.reason or self.adopted:
+            _fail("Recording after stop or finish violates the buffered contract.")
+        if set(progress) - {"check_index", "work"}:
+            _fail("Unknown progress field.")
+        index = progress["check_index"]
+        work = progress.get("work", {})
+        if type(index) is not int or not 0 <= index <= MAX_SAFE_INTEGER or type(work) is not dict or any(type(v) is not int or not 0 <= v <= MAX_SAFE_INTEGER for v in work.values()):
+            _fail("Progress must contain nonnegative safe integers.")
+        previous = self.points[-1] if self.points else None
+        expected = previous["check_index"] + self.schedule["every"] if previous else self.schedule["start"]
+        if previous and (index <= previous["check_index"] or any(work.get(k, -1) < v for k, v in previous["work"].items())):
+            _fail("Progress and work counts must be monotonic.")
+        if index > expected:
+            _fail("A scheduled check was skipped.")
+        expired = self.clock() >= self.active_ns
+        if not terminal and not expired and index != expected:
+            return Decision()
+        metrics = measure()
+        if type(metrics) is not dict:
+            _fail("Provisional metrics must be a JSON object.")
+        metrics = parse_json(canonical_bytes(metrics))
+        elapsed = self.clock()
+        if type(elapsed) is not int or not 0 <= elapsed <= MAX_SAFE_INTEGER or (previous and elapsed < previous["instrumented_time_ns"]):
+            _fail("Instrumented clock must be monotonic safe nanoseconds.")
+        metric = self.policy.get("metric")
+        value = metrics.get(metric) if metric else None
+        if metric and (type(value) not in (int, float)):
+            _fail("Provisional target metric must be finite and numeric.")
+        crossed = [t for t in self.thresholds if t not in self.reached and self._reaches(value, t)]
+        reason = ("target_reached" if metric and self._reaches(value, self.policy["threshold"]) else
+                  "implementation_stopped" if terminal else
+                  "active_time_limit" if elapsed >= self.active_ns else
+                  "trace_limit" if len(self.points) + 1 >= self.policy["max-trace-points"] else None)
+        capture = not metric or bool(crossed) or reason is not None
+        if capture and len(self.snapshots) + 1 >= self.policy["max-observations"] and reason is None:
+            reason = "observation_limit" if metric else "fixed_count"
+        point = {"check_index": index, "work": parse_json(canonical_bytes(work)), "provisional_metrics": metrics,
+                 "instrumented_time_ns": elapsed, "terminal": reason is not None}
+        extra = len(canonical_bytes(point)) + 1
+        regular = self.policy["max-buffer-bytes"] - self.policy["terminal-reserve-bytes"]
+        if reason is None and self._estimate(extra, None) > regular:
+            reason = "byte_limit"
+            point["terminal"] = True
+            extra = len(canonical_bytes(point)) + 1
+        data = self._snapshot(snapshot) if capture or reason else None
+        if reason is None and self._estimate(extra, data) > regular:
+            reason = "byte_limit"
+            point["terminal"] = True
+            extra = len(canonical_bytes(point)) + 1
+        if self._estimate(extra, data) > self.policy["max-buffer-bytes"]:
+            _fail("Terminal check and snapshot exceed max-buffer-bytes.", "resource_limit")
+        self.trace_bytes += extra
+        self.points.append(point)
+        if data is not None:
+            self._capture(data, crossed)
+        self.reached.extend(crossed)
+        self.reason = reason
+        return Decision(reason)
+
+    def _capture(self, data, thresholds):
+        ordinal = len(self.snapshots)
+        if ordinal >= self.policy["max-observations"]:
+            _fail("Terminal snapshot exceeds max-observations.", "resource_limit")
+        self.snapshots.append({"capture_ordinal": ordinal, "trace_index": len(self.points) - 1,
+                               "thresholds": thresholds, "manifest": f"snapshots/{ordinal}/result.json"})
+        self.data.append(data)
+        self.snapshot_bytes += len(data)
+
+    def _manifest(self, total, reason, files):
+        return {"schema_version": 1, "complete": True, "clock": "monotonic_ns",
+                "instrumented_scope": self.profile["instrumented_scope"], "instrumented_total_time_ns": total,
+                "stop_reason": reason, "trace": "trace.jsonl", "snapshots": self.snapshots.copy(), "files": files}
+
+    def _estimate(self, extra, data):
+        files = [{"path": "trace.jsonl", "sha256": "0" * 64, "size_bytes": self.trace_bytes + extra}]
+        files.extend({"path": s["manifest"], "sha256": "0" * 64, "size_bytes": len(b)} for s, b in zip(self.snapshots, self.data))
+        manifest = self._manifest(MAX_SAFE_INTEGER, "implementation_stopped", files)
+        if data is not None:
+            ordinal = len(self.snapshots)
+            path = f"snapshots/{ordinal}/result.json"
+            manifest["snapshots"].append({"capture_ordinal": ordinal, "trace_index": len(self.points), "thresholds": self.thresholds, "manifest": path})
+            files.append({"path": path, "sha256": "0" * 64, "size_bytes": len(data)})
+        return self.trace_bytes + extra + self.snapshot_bytes + (len(data) if data is not None else 0) + len(canonical_bytes(manifest))
+
+    def finish(self, progress, measure, snapshot):
+        if self.finished:
+            _fail("Buffer was already finished.")
+        if self.points and progress["check_index"] == self.points[-1]["check_index"]:
+            if progress.get("work", {}) != self.points[-1]["work"]:
+                _fail("Terminal work changed without advancing progress.")
+            if not self.snapshots or self.snapshots[-1]["trace_index"] != len(self.points) - 1:
+                data = self._snapshot(snapshot)
+                if self._estimate(0, data) > self.policy["max-buffer-bytes"]:
+                    _fail("Terminal snapshot does not fit.", "resource_limit")
+                self._capture(data, [])
+            self.points[-1]["terminal"] = True
+        else:
+            self._check(progress, measure, snapshot, True)
+        self.reason = self.reason or "implementation_stopped"
+        self.total = self.clock()
+        if type(self.total) is not int or not self.points[-1]["instrumented_time_ns"] <= self.total <= MAX_SAFE_INTEGER:
+            _fail("Invalid total instrumented duration.")
+        self.finished = True
+
+    def adopt_buffer(self, manifest="buffer.json"):
+        if self.points or self.finished:
+            _fail("Cannot combine a native buffer with another trajectory.")
+        manifest = _relative_path(manifest)
+        self.adopted = manifest
+        self.finished = True
+
+    def write(self):
+        if not self.finished:
+            _fail("execute_buffered must finish the terminal check before returning.")
+        if self.adopted:
+            return self.adopted
+        self.directory.mkdir(parents=True, exist_ok=True)
+        trace = b"".join(canonical_bytes(p) + b"\n" for p in self.points)
+        (self.directory / "trace.jsonl").write_bytes(trace)
+        files = [_file("trace.jsonl", trace)]
+        for saved, data in zip(self.snapshots, self.data):
+            path = self.directory / saved["manifest"]
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(data)
+            files.append(_file(saved["manifest"], data))
+        manifest = canonical_bytes(self._manifest(self.total, self.reason, files))
+        if len(trace) + self.snapshot_bytes + len(manifest) > self.policy["max-buffer-bytes"]:
+            _fail("Completed buffer exceeds byte bound.", "resource_limit")
+        (self.directory / "buffer.json").write_bytes(manifest)
+        return "buffer.json"

metewand/_canonical.py

@@ -0,0 +1,125 @@
+"""The restricted version-1 JSON domain and RFC 8785 encoding."""
+
+import json
+import math
+
+MAX_SAFE_INTEGER = (1 << 53) - 1
+
+
+class CanonicalJsonError(ValueError):
+    """A value cannot be represented by Metewand's canonical JSON contract."""
+
+
+def _normalize(value):
+    if value is None or type(value) is bool:
+        return value
+    if type(value) is str:
+        value.encode("utf-8")
+        return value
+    if type(value) is int:
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise CanonicalJsonError(
+                "Integers must lie in the inclusive 53-bit safe range."
+            )
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise CanonicalJsonError("Numbers must be finite binary64 values.")
+        if value.is_integer():
+            return _normalize(int(value))
+        return value
+    if type(value) is list:
+        return [_normalize(item) for item in value]
+    if type(value) is dict:
+        if any(type(key) is not str for key in value):
+            raise CanonicalJsonError("Object keys must be strings.")
+        return {_normalize(key): _normalize(item) for key, item in value.items()}
+    raise CanonicalJsonError(f"Unsupported JSON value type: {type(value).__name__}.")
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise CanonicalJsonError(f"Duplicate JSON object key: {key!r}.")
+        result[key] = value
+    return result
+
+
+def _invalid_constant(value):
+    raise CanonicalJsonError(f"Invalid JSON number: {value}.")
+
+
+def parse_json(source):
+    """Parse UTF-8 bytes or text, rejecting duplicate keys and noncanonical values.
+
+    The returned value normalizes integral floats and negative zero to integers.
+    Source whitespace and property order need not be canonical.
+    """
+    try:
+        if isinstance(source, bytes):
+            source = source.decode("utf-8")
+        if not isinstance(source, str):
+            raise CanonicalJsonError("JSON input must be UTF-8 bytes or text.")
+        return _normalize(
+            json.loads(
+                source,
+                object_pairs_hook=_unique_object,
+                parse_constant=_invalid_constant,
+            )
+        )
+    except (ValueError, UnicodeError, RecursionError) as error:
+        raise CanonicalJsonError(str(error)) from error
+
+
+def _float_text(value):
+    # Python supplies the shortest round-tripping digits; ECMAScript uses a
+    # different threshold for exponent notation and omits exponent zero padding.
+    text = repr(value)
+    if "e" not in text:
+        return text
+    mantissa, exponent = text.split("e")
+    exponent = int(exponent)
+    if abs(value) < 1e-6:
+        return f"{mantissa}e{exponent}"
+    negative = mantissa.startswith("-")
+    digits = mantissa.lstrip("-").replace(".", "")
+    point = 1 + exponent
+    if point <= 0:
+        text = "0." + "0" * -point + digits
+    elif point >= len(digits):
+        text = digits + "0" * (point - len(digits))
+    else:
+        text = digits[:point] + "." + digits[point:]
+    return ("-" if negative else "") + text
+
+
+def _encode(value):
+    if value is None:
+        return "null"
+    if type(value) is bool:
+        return "true" if value else "false"
+    if type(value) is str:
+        return json.dumps(value, ensure_ascii=False)
+    if type(value) is int:
+        return str(value)
+    if type(value) is float:
+        return _float_text(value)
+    if type(value) is list:
+        return "[" + ",".join(_encode(item) for item in value) + "]"
+    keys = sorted(value, key=lambda key: key.encode("utf-16-be"))
+    return (
+        "{" + ",".join(_encode(key) + ":" + _encode(value[key]) for key in keys) + "}"
+    )
+
+
+def canonical_bytes(value):
+    """Encode built-in JSON values as canonical UTF-8 bytes without a newline.
+
+    This never coerces tuples, arrays, custom scalars, or nonstring object keys.
+    Convert library-specific values explicitly in benchmark code.
+    """
+    try:
+        return _encode(_normalize(value)).encode("utf-8")
+    except (ValueError, UnicodeError, RecursionError) as error:
+        raise CanonicalJsonError(str(error)) from error

metewand/_functions.py

@@ -0,0 +1,103 @@
+"""Ordinary scientific functions backed by the existing worker lifecycle."""
+
+from dataclasses import dataclass
+import importlib.util
+from pathlib import Path
+import sys
+
+from ._artifacts import file_entry, read_json, write_dataset_manifest, write_json
+from ._worker import Evaluation, OneShotImplementation, _serve_fds
+
+
+@dataclass(frozen=True)
+class FunctionContext:
+    """Role parameters, problem parameters, seed, and declared scientific rules."""
+
+    parameters: dict
+    problem_parameters: dict
+    seed: int | None
+    semantics: dict
+
+
+def materialize_function(function, source_dir, parameters, seed, output_dir):
+    data = function(FunctionContext(parameters, {}, seed, {}))
+    if type(data) is not dict:
+        raise TypeError("A dataset function must return a JSON-compatible object.")
+    write_json(output_dir / "data.json", data)
+    return write_dataset_manifest(output_dir, [file_entry(output_dir, "data.json", "application/json")])
+
+
+def read_function_data(dataset):
+    path = dataset / "data.json"
+    if not path.exists() and not any(dataset.iterdir()):
+        return {}
+    data = read_json(path)
+    if type(data) is not dict:
+        raise TypeError("A function dataset must contain a JSON object in data.json.")
+    return data
+
+
+class FunctionImplementation(OneShotImplementation):
+    def __init__(self, function):
+        self.function = function
+
+    def prepare(self, dataset, contract, problem_parameters, parameters, seed):
+        self.data = read_function_data(dataset)
+        self.context = FunctionContext(parameters, problem_parameters, seed, {})
+
+    def execute(self, budget, observation_control):
+        return self.function(self.data, self.context)
+
+    def reset(self):
+        self.data = None
+        self.context = None
+
+
+def evaluate_function(function, data, result, context):
+    outcome = function(data, result, context)
+    completion = context.semantics.get("one_shot_completion", {})
+    if isinstance(outcome, Evaluation):
+        if not completion and outcome.verdict in {"reached", "not_reached"}:
+            raise ValueError("A completion verdict requires declared completion rules; use not_required or invalid.")
+        if completion and outcome.verdict == "not_required":
+            raise ValueError("Declared completion rules require an explicit completion verdict.")
+        return outcome
+    if context.semantics.get("validity") or completion:
+        raise ValueError("Scientific validity or completion rules require an explicit Evaluation verdict.")
+    return Evaluation(outcome, "not_required")
+
+
+def serve_function(role, file, name):
+    """Load one explicitly selected function inside an authorized worker process."""
+    file = Path(file)
+    function = None
+
+    def initialize():
+        nonlocal function
+        # Loading during hello excludes imports from default timing and reports errors.
+        sys.path.insert(0, str(file.parent))
+        spec = importlib.util.spec_from_file_location("_metewand_benchmark", file)
+        if spec is None or spec.loader is None:
+            raise ValueError(f"Cannot load function source {file}.")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = module
+        spec.loader.exec_module(module)
+        function = getattr(module, name, None)
+        if not callable(function):
+            raise ValueError(f"{file}:{name} does not identify a callable function.")
+
+    def call(*args):
+        return function(*args)
+
+    if role == "dataset_materializer":
+        _serve_fds(lambda *args: materialize_function(call, *args), role, None, None, initialize=initialize)
+    elif role == "implementation":
+        _serve_fds(FunctionImplementation(call), role, None, None, initialize=initialize)
+    elif role == "problem_evaluator":
+        def evaluate(dataset, contract, parameters, semantics, result_dir, metrics_path):
+            data = read_function_data(dataset)
+            result = read_json(result_dir / "result.json")["data"]
+            return evaluate_function(call, data, result, FunctionContext(parameters, parameters, None, semantics))
+        _serve_fds(evaluate, role, None, None, semantics=True, initialize=initialize)
+    else:
+        raise ValueError(f"Unknown function worker role: {role}.")