sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/workflow_registry.py

@@ -0,0 +1,513 @@
+"""Operator-owned extension registration for the shared workflow.
+
+Registration and discovery inspect declared metadata only. They do not import
+extensions, read assets, validate payloads, execute candidates, or run evaluator
+and policy callbacks. The operator supplies objects explicitly. Their declared
+implementation labels identify a binding; they do not authenticate source bytes.
+
+Each role has an independent ID space. Native catalogs remain authoritative for
+native records; this registry contains only explicitly enabled common extensions.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Collection, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .workflow_contracts import (
+    BackendDescriptor, CaseProvider, Criterion, Dataset, DatasetDefinition,
+    EvaluatorDefinition, MetricSpec, PayloadSchema, SuiteDefinition,
+    WorkflowBackend, WorkflowContractError, _object, _text, _thaw,
+    contract_digest,
+)
+
+_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/@+\-]*\Z")
+_BACKEND_METHODS = (
+    "describe", "cases", "resolve", "admit", "recheck", "execute",
+    "accepts_reference", "reference", "assess", "report", "assessments", "compare",
+)
+_POLICY_KINDS = frozenset({"aggregation", "comparison", "report", "decision"})
+
+
+class WorkflowRegistryError(WorkflowContractError):
+    """An extension is missing, incompatible, duplicated, or has drifted."""
+
+
+@dataclass(frozen=True)
+class CallbackDefinition:
+    """Declared policy/projection identity; lookup never invokes its callback."""
+
+    callback_id: str
+    version: str
+    implementation_id: str
+    kind: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name in ("callback_id", "version", "implementation_id", "kind"):
+            _text(getattr(self, name), name)
+        object.__setattr__(self, "metadata", _object(self.metadata, "metadata"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"callback_id": self.callback_id, "version": self.version,
+                "implementation_id": self.implementation_id, "kind": self.kind,
+                "metadata": _thaw(self.metadata)}
+
+
+@dataclass(frozen=True)
+class _ProviderSchemaBinding:
+    role: str
+    digest: str
+    validator: Callable[..., Any] = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class _Registration:
+    value: Any
+    definition: Any
+    digest: str
+    callback: Callable[..., Any] | None = None
+    schema_bindings: tuple[_ProviderSchemaBinding, ...] | None = None
+
+
+class WorkflowRegistry:
+    """Explicit, mutable operator registry with pinned registration metadata.
+
+    IDs are namespaced by default. ``legacy_ids`` permits an operator's exact,
+    known opaque native IDs without relaxing the convention for new extensions.
+    Duplicate IDs within a role are rejected, even for another version. Use a
+    separate registry to select a different binding. Criterion and metric IDs
+    may have the same spelling without implying a one-to-one relationship.
+
+    Backend ``descriptor``/``describe`` and provider ``definition`` must be pure
+    metadata access. Registration/discovery do not call asset or runtime methods.
+    ``resolve_suite`` checks declared cross-references and descriptor drift; it
+    is not execution admission and does not grant reference access.
+
+    Register a concrete Dataset's input, reference and selection schemas first.
+    Registration and provider lookup require their exact registered metadata
+    and validator bindings. Custom CaseProvider implementations remain subject
+    to their backend's validation contract; the registry does not inspect their
+    private schema implementation or invoke provider methods to discover it.
+    """
+
+    def __init__(self, *, legacy_ids: Collection[str] = ()) -> None:
+        if isinstance(legacy_ids, (str, bytes)) or not isinstance(legacy_ids, Collection):
+            raise WorkflowRegistryError("legacy_ids must be an explicit collection of native IDs")
+        self._legacy_ids = frozenset(_text(value, "legacy ID") for value in legacy_ids)
+        self._stores: dict[str, dict[str, _Registration]] = {
+            role: {} for role in ("backend", "schema", "dataset", "provider", "criterion",
+                                 "evaluator", "metric", "suite", "policy", "projection")
+        }
+
+    def _id(self, value: str, role: str) -> str:
+        _text(value, role + " ID")
+        if not _IDENTIFIER.fullmatch(value):
+            raise WorkflowRegistryError(f"{role} ID must be a stable identifier")
+        if "." not in value and ":" not in value and value not in self._legacy_ids:
+            raise WorkflowRegistryError(f"{role} ID must be namespaced or an explicit legacy ID")
+        return value
+
+    def fork(self) -> WorkflowRegistry:
+        """Stage trusted registrations without changing this registry's stores.
+
+        Bindings keep their exact validator, callback and implementation objects.
+        This isolates registration membership on factory failure. It does not
+        sandbox trusted code or copy mutable state inside an implementation.
+        Lookup still checks the original registration pins for drift.
+        """
+        for identifier in self._stores["backend"]:
+            self.get_backend(identifier)
+        for identifier in self._stores["schema"]:
+            self.get_schema(identifier)
+        for identifier in self._stores["provider"]:
+            self.get_provider(identifier)
+        selected = WorkflowRegistry(legacy_ids=self._legacy_ids)
+        selected._stores = {role: dict(rows) for role, rows in self._stores.items()}
+        return selected
+
+    def _register(self, role: str, identifier: str, value: Any, definition: Any,
+                  callback: Callable[..., Any] | None = None, *,
+                  schema_bindings: tuple[_ProviderSchemaBinding, ...] | None = None) -> None:
+        identifier = self._id(identifier, role)
+        if identifier in self._stores[role]:
+            raise WorkflowRegistryError(f"duplicate {role} ID: {identifier}")
+        self._stores[role][identifier] = _Registration(
+            value, definition, contract_digest(definition.to_dict()), callback, schema_bindings,
+        )
+
+    def _get(self, role: str, identifier: str) -> _Registration:
+        self._id(identifier, role)
+        try:
+            return self._stores[role][identifier]
+        except KeyError:
+            raise WorkflowRegistryError(f"unregistered {role}: {identifier}") from None
+
+    def _definitions(self, role: str) -> tuple[Any, ...]:
+        # These are frozen snapshots captured during registration, not live
+        # backend/provider properties or runtime callbacks.
+        return tuple(self._stores[role][key].definition for key in sorted(self._stores[role]))
+
+    @staticmethod
+    def _unchanged(registration: _Registration, definition: Any, role: str) -> None:
+        if contract_digest(definition.to_dict()) != registration.digest:
+            raise WorkflowRegistryError(f"registered {role} metadata has changed")
+
+    def register_backend(self, backend: WorkflowBackend) -> BackendDescriptor:
+        descriptor = getattr(backend, "descriptor", None)
+        if not isinstance(descriptor, BackendDescriptor):
+            raise WorkflowRegistryError("backend requires a BackendDescriptor")
+        if any(not callable(getattr(backend, name, None)) for name in _BACKEND_METHODS):
+            raise WorkflowRegistryError("backend does not implement the workflow protocol")
+        from .execution_capabilities import execution_paths
+        try:
+            execution_paths(descriptor)
+        except WorkflowContractError as exc:
+            raise WorkflowRegistryError(str(exc)) from None
+        for suite_id in descriptor.suite_ids:
+            self._id(suite_id, "suite")
+        self._register("backend", descriptor.backend_id, backend, descriptor)
+        return descriptor
+
+    def get_backend(self, backend_id: str) -> WorkflowBackend:
+        registration = self._get("backend", backend_id)
+        descriptor = getattr(registration.value, "descriptor", None)
+        if not isinstance(descriptor, BackendDescriptor):
+            raise WorkflowRegistryError("registered backend descriptor is invalid")
+        self._unchanged(registration, descriptor, "backend")
+        return registration.value
+
+    def list_backends(self) -> tuple[BackendDescriptor, ...]:
+        return self._definitions("backend")
+
+    def register_schema(self, schema: PayloadSchema) -> PayloadSchema:
+        if not isinstance(schema, PayloadSchema):
+            raise WorkflowRegistryError("schema must be PayloadSchema")
+        self._register("schema", schema.schema_id, schema, schema, schema.validator)
+        return schema
+
+    def get_schema(self, schema_id: str) -> PayloadSchema:
+        registration = self._get("schema", schema_id)
+        self._unchanged(registration, registration.value, "schema")
+        if registration.value.validator is not registration.callback:
+            raise WorkflowRegistryError("registered schema validator has changed")
+        return registration.value
+
+    def list_schemas(self) -> tuple[PayloadSchema, ...]:
+        return self._definitions("schema")
+
+    def validate_payload(self, schema_id: str, value: Any) -> Any:
+        """Explicitly execute the registered validator on a detached snapshot."""
+        return self.get_schema(schema_id).validate(value)
+
+    def register_dataset(self, definition: DatasetDefinition) -> DatasetDefinition:
+        if not isinstance(definition, DatasetDefinition):
+            raise WorkflowRegistryError("dataset must be DatasetDefinition")
+        for role, identifier in (("provider", definition.provider_id),
+                                 ("schema", definition.input_schema_id)):
+            self._id(identifier, role)
+        if definition.reference_schema_id is not None:
+            self._id(definition.reference_schema_id, "schema")
+        self._register("dataset", definition.dataset_id, definition, definition)
+        return definition
+
+    def get_dataset(self, dataset_id: str) -> DatasetDefinition:
+        registration = self._get("dataset", dataset_id)
+        self._unchanged(registration, registration.value, "dataset")
+        return registration.value
+
+    def list_datasets(self) -> tuple[DatasetDefinition, ...]:
+        return self._definitions("dataset")
+
+    def _provider_schema_bindings(self, provider: CaseProvider,
+                                  definition: DatasetDefinition) -> tuple[_ProviderSchemaBinding, ...] | None:
+        if not isinstance(provider, Dataset):
+            return None
+        bindings = []
+        for role, schema, expected_id in (
+            ("input", provider.input_schema, definition.input_schema_id),
+            ("reference", provider.reference_schema, definition.reference_schema_id),
+            ("selection", provider.selection_schema, None),
+        ):
+            if schema is None and role != "input":
+                continue
+            if not isinstance(schema, PayloadSchema):
+                raise WorkflowRegistryError(f"concrete dataset {role} schema is invalid")
+            if role != "selection" and schema.schema_id != expected_id:
+                raise WorkflowRegistryError(f"concrete dataset {role} schema differs from its definition")
+            registered = self.get_schema(schema.schema_id)
+            digest = contract_digest(schema.to_dict())
+            if (digest != contract_digest(registered.to_dict())
+                    or schema.validator is not registered.validator):
+                raise WorkflowRegistryError(f"concrete dataset {role} schema differs from registered binding")
+            bindings.append(_ProviderSchemaBinding(role, digest, schema.validator))
+        return tuple(bindings)
+
+    def register_provider(self, provider: CaseProvider) -> DatasetDefinition:
+        definition = getattr(provider, "definition", None)
+        if not isinstance(definition, DatasetDefinition):
+            raise WorkflowRegistryError("provider requires a DatasetDefinition")
+        if not callable(getattr(provider, "cases", None)) or not callable(getattr(provider, "reference_for", None)):
+            raise WorkflowRegistryError("provider does not implement the case-provider protocol")
+        self._id(definition.provider_id, "provider")
+        if definition.provider_id in self._stores["provider"]:
+            raise WorkflowRegistryError(f"duplicate provider ID: {definition.provider_id}")
+        existing = self._stores["dataset"].get(definition.dataset_id)
+        if existing is not None and existing.digest != contract_digest(definition.to_dict()):
+            raise WorkflowRegistryError("provider definition differs from registered dataset")
+        bindings = self._provider_schema_bindings(provider, definition)
+        if existing is None:
+            self.register_dataset(definition)
+        self._register("provider", definition.provider_id, provider, definition,
+                       schema_bindings=bindings)
+        return definition
+
+    def get_provider(self, provider_id: str) -> CaseProvider:
+        registration = self._get("provider", provider_id)
+        definition = getattr(registration.value, "definition", None)
+        if not isinstance(definition, DatasetDefinition):
+            raise WorkflowRegistryError("registered provider definition is invalid")
+        self._unchanged(registration, definition, "provider")
+        current = self._provider_schema_bindings(registration.value, definition)
+        expected = registration.schema_bindings
+        if ((current is None) != (expected is None)
+                or (current is not None and expected is not None
+                    and (len(current) != len(expected)
+                         or any(a.role != b.role or a.digest != b.digest or a.validator is not b.validator
+                                for a, b in zip(current, expected))))):
+            raise WorkflowRegistryError("registered concrete dataset schema bindings have changed")
+        return registration.value
+
+    def list_providers(self) -> tuple[DatasetDefinition, ...]:
+        return self._definitions("provider")
+
+    def register_criterion(self, criterion: Criterion) -> Criterion:
+        if not isinstance(criterion, Criterion):
+            raise WorkflowRegistryError("criterion must be Criterion")
+        self._register("criterion", criterion.criterion_id, criterion, criterion)
+        return criterion
+
+    def get_criterion(self, criterion_id: str) -> Criterion:
+        registration = self._get("criterion", criterion_id)
+        self._unchanged(registration, registration.value, "criterion")
+        return registration.value
+
+    def list_criteria(self) -> tuple[Criterion, ...]:
+        return self._definitions("criterion")
+
+    def register_evaluator(self, definition: EvaluatorDefinition,
+                           evaluator: Callable[..., Any] | None = None) -> EvaluatorDefinition:
+        if not isinstance(definition, EvaluatorDefinition):
+            raise WorkflowRegistryError("evaluator must be EvaluatorDefinition")
+        if evaluator is not None and not callable(evaluator):
+            raise WorkflowRegistryError("evaluator callback must be callable")
+        for role, identifiers in (("criterion", definition.criterion_ids),
+                                  ("schema", definition.assessment_schema_ids),
+                                  ("metric", definition.metric_ids)):
+            for identifier in identifiers:
+                self._id(identifier, role)
+        self._register("evaluator", definition.evaluator_id, definition, definition, evaluator)
+        return definition
+
+    def get_evaluator(self, evaluator_id: str) -> EvaluatorDefinition:
+        registration = self._get("evaluator", evaluator_id)
+        self._unchanged(registration, registration.value, "evaluator")
+        return registration.value
+
+    def get_evaluator_callable(self, evaluator_id: str) -> Callable[..., Any]:
+        self.get_evaluator(evaluator_id)
+        callback = self._get("evaluator", evaluator_id).callback
+        if callback is None:
+            raise WorkflowRegistryError("evaluator execution is backend-owned; no callback is registered")
+        return callback
+
+    def list_evaluators(self) -> tuple[EvaluatorDefinition, ...]:
+        return self._definitions("evaluator")
+
+    def register_metric(self, metric: MetricSpec) -> MetricSpec:
+        if not isinstance(metric, MetricSpec):
+            raise WorkflowRegistryError("metric must be MetricSpec")
+        for policy_id in (metric.aggregation_policy, metric.comparison_policy):
+            if policy_id is not None:
+                self._id(policy_id, "policy")
+        self._register("metric", metric.metric_id, metric, metric)
+        return metric
+
+    def get_metric(self, metric_id: str) -> MetricSpec:
+        registration = self._get("metric", metric_id)
+        self._unchanged(registration, registration.value, "metric")
+        return registration.value
+
+    def list_metrics(self) -> tuple[MetricSpec, ...]:
+        return self._definitions("metric")
+
+    def register_suite(self, suite: SuiteDefinition) -> SuiteDefinition:
+        if not isinstance(suite, SuiteDefinition):
+            raise WorkflowRegistryError("suite must be SuiteDefinition")
+        self._id(suite.backend_id, "backend")
+        for role, identifiers in (("criterion", suite.criterion_ids),
+                                  ("evaluator", suite.evaluator_ids), ("metric", suite.metric_ids)):
+            for identifier in identifiers:
+                self._id(identifier, role)
+        for dataset in suite.datasets:
+            self._id(dataset.dataset_id, "dataset")
+        self._register("suite", suite.suite_id, suite, suite)
+        return suite
+
+    def get_suite(self, suite_id: str) -> SuiteDefinition:
+        registration = self._get("suite", suite_id)
+        self._unchanged(registration, registration.value, "suite")
+        return registration.value
+
+    def list_suites(self) -> tuple[SuiteDefinition, ...]:
+        return self._definitions("suite")
+
+    def register_policy(self, policy_id: str, *, version: str, implementation_id: str,
+                        kind: str, callback: Callable[..., Any] | None = None,
+                        metadata: Mapping[str, Any] | None = None) -> CallbackDefinition:
+        if type(kind) is not str or kind not in _POLICY_KINDS:
+            raise WorkflowRegistryError("policy kind must be aggregation, comparison, report, or decision")
+        if callback is not None and not callable(callback):
+            raise WorkflowRegistryError("policy callback must be callable")
+        definition = CallbackDefinition(policy_id, version, implementation_id, kind,
+                                        metadata if metadata is not None else {})
+        self._register("policy", policy_id, definition, definition, callback)
+        return definition
+
+    def get_policy(self, policy_id: str, *, kind: str | None = None) -> CallbackDefinition:
+        registration = self._get("policy", policy_id)
+        self._unchanged(registration, registration.value, "policy")
+        if kind is not None and registration.definition.kind != kind:
+            raise WorkflowRegistryError(f"policy {policy_id} has incompatible kind")
+        return registration.value
+
+    def get_policy_callable(self, policy_id: str, *, kind: str | None = None) -> Callable[..., Any]:
+        self.get_policy(policy_id, kind=kind)
+        callback = self._get("policy", policy_id).callback
+        if callback is None:
+            raise WorkflowRegistryError("policy execution is backend-owned; no callback is registered")
+        return callback
+
+    def list_policies(self) -> tuple[CallbackDefinition, ...]:
+        return self._definitions("policy")
+
+    def register_projection(self, schema_id: str, projector: Callable[..., Any], *,
+                            version: str, implementation_id: str,
+                            metadata: Mapping[str, Any] | None = None) -> CallbackDefinition:
+        self.get_schema(schema_id)
+        if not callable(projector):
+            raise WorkflowRegistryError("projection callback must be callable")
+        definition = CallbackDefinition(schema_id, version, implementation_id, "projection",
+                                        metadata if metadata is not None else {})
+        self._register("projection", schema_id, definition, definition, projector)
+        return definition
+
+    def get_projection(self, schema_id: str) -> CallbackDefinition:
+        registration = self._get("projection", schema_id)
+        self._unchanged(registration, registration.value, "projection")
+        self.get_schema(schema_id)
+        return registration.value
+
+    def get_projection_callable(self, schema_id: str) -> Callable[..., Any]:
+        self.get_projection(schema_id)
+        callback = self._get("projection", schema_id).callback
+        assert callback is not None
+        return callback
+
+    def list_projections(self) -> tuple[CallbackDefinition, ...]:
+        return self._definitions("projection")
+
+    def resolve_suite(self, suite_id: str, *, scope: str | None = None,
+                      mode: str | None = None) -> tuple[SuiteDefinition, WorkflowBackend]:
+        """Bind pure metadata and check capabilities; do not admit execution."""
+        suite = self.get_suite(suite_id)
+        backend = self.get_backend(suite.backend_id)
+        descriptor = self._get("backend", suite.backend_id).definition
+        all_required_capabilities = set(suite.required_capabilities)
+        if descriptor.suite_ids and suite.suite_id not in descriptor.suite_ids:
+            raise WorkflowRegistryError("backend does not declare the selected suite")
+        if scope is not None and scope not in descriptor.supported_scopes:
+            raise WorkflowRegistryError(f"backend does not support scope {scope!r}")
+        if mode is not None and mode not in descriptor.supported_modes:
+            raise WorkflowRegistryError(f"backend does not support mode {mode!r}")
+        if not set(suite.required_capabilities).issubset(descriptor.capabilities):
+            raise WorkflowRegistryError("backend lacks required suite capabilities")
+        from .execution_capabilities import validate_execution_requirement
+        try:
+            validate_execution_requirement(descriptor, scope=scope, mode=mode,
+                                           capabilities=suite.required_capabilities)
+            if "evaluation_protocol" in suite.metadata:
+                from .evaluation_protocols import EvaluationProtocol, PROTOCOL_SCHEMA
+                protocol = EvaluationProtocol.from_dict(suite.metadata["evaluation_protocol"])
+                all_required_capabilities.add(PROTOCOL_SCHEMA)
+                validate_execution_requirement(descriptor, scope=scope, mode=mode,
+                                               capabilities=(PROTOCOL_SCHEMA,))
+                self.get_schema(protocol.input_schema_id)
+                self.get_schema(protocol.output_schema_id)
+                if any(item.input_schema_id != protocol.input_schema_id for item in suite.datasets):
+                    raise WorkflowRegistryError("protocol input schema differs from suite datasets")
+        except WorkflowContractError as exc:
+            raise WorkflowRegistryError(str(exc)) from None
+        for criterion_id in suite.criterion_ids:
+            self.get_criterion(criterion_id)
+        for metric_id in suite.metric_ids:
+            metric = self.get_metric(metric_id)
+            if metric.aggregation_policy is not None:
+                self.get_policy(metric.aggregation_policy, kind="aggregation")
+            if metric.comparison_policy is not None:
+                self.get_policy(metric.comparison_policy, kind="comparison")
+        for evaluator_id in suite.evaluator_ids:
+            evaluator = self.get_evaluator(evaluator_id)
+            all_required_capabilities.update(evaluator.required_capabilities)
+            if not set(evaluator.required_capabilities).issubset(descriptor.capabilities):
+                raise WorkflowRegistryError("backend lacks required evaluator capabilities")
+            try:
+                validate_execution_requirement(descriptor, scope=scope, mode=mode,
+                                               capabilities=evaluator.required_capabilities)
+            except WorkflowContractError as exc:
+                raise WorkflowRegistryError(str(exc)) from None
+            if not set(evaluator.criterion_ids).issubset(suite.criterion_ids):
+                raise WorkflowRegistryError("evaluator refers to criteria outside the suite")
+            if not set(evaluator.metric_ids).issubset(suite.metric_ids):
+                raise WorkflowRegistryError("evaluator refers to metrics outside the suite")
+            for schema_id in evaluator.assessment_schema_ids:
+                self.get_schema(schema_id)
+        for dataset in suite.datasets:
+            registered = self.get_dataset(dataset.dataset_id)
+            if contract_digest(registered.to_dict()) != contract_digest(dataset.to_dict()):
+                raise WorkflowRegistryError("suite dataset differs from registered definition")
+            provider = self.get_provider(dataset.provider_id)
+            if contract_digest(provider.definition.to_dict()) != contract_digest(dataset.to_dict()):
+                raise WorkflowRegistryError("case provider differs from suite dataset")
+            self.get_schema(dataset.input_schema_id)
+            if dataset.reference_schema_id is not None:
+                self.get_schema(dataset.reference_schema_id)
+        try:
+            validate_execution_requirement(descriptor, scope=scope, mode=mode,
+                                           capabilities=tuple(sorted(all_required_capabilities)))
+        except WorkflowContractError as exc:
+            raise WorkflowRegistryError(str(exc)) from None
+        described = backend.describe(suite_id)
+        if not isinstance(described, SuiteDefinition) or described.definition_digest != suite.definition_digest:
+            raise WorkflowRegistryError("backend suite description differs from registered definition")
+        self.get_backend(suite.backend_id)
+        return suite, backend
+
+    def verify_suite(self, suite: str | SuiteDefinition, *, scope: str | None = None,
+                     mode: str | None = None) -> tuple[SuiteDefinition, WorkflowBackend]:
+        """Check a registered suite or require an exact supplied metadata match."""
+        if isinstance(suite, SuiteDefinition):
+            registered = self.get_suite(suite.suite_id)
+            if registered.definition_digest != suite.definition_digest:
+                raise WorkflowRegistryError("supplied suite differs from registered definition")
+            suite_id = suite.suite_id
+        else:
+            suite_id = suite
+        return self.resolve_suite(suite_id, scope=scope, mode=mode)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return registration metadata only; do not call backend/provider code."""
+        return {"schema_version": "sphynx.workflow-registry.v1",
+                "roles": {role: [item.to_dict() for item in self._definitions(role)]
+                          for role in self._stores}}