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

sphynx/workflow_decisions.py

@@ -0,0 +1,211 @@
+"""Explicit decision callbacks over permitted saved-report snapshots.
+
+A verdict records a selected policy's outcome. It does not execute candidates,
+create a grading pass, grant access, or upgrade native evidence authority.
+"""
+from __future__ import annotations
+
+import html
+import inspect
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Mapping, TYPE_CHECKING
+
+from .workflow_contracts import (
+    BackendDescriptor, ReferenceBinding, WorkflowContractError,
+    _object, _text, _thaw, contract_digest,
+)
+from .workflow_registry import CallbackDefinition
+
+if TYPE_CHECKING:
+    from .workflows import Report
+
+
+class DecisionPolicyError(WorkflowContractError):
+    """A selected decision callback failed or returned an invalid outcome."""
+
+
+def _reference_dict(reference: ReferenceBinding) -> dict:
+    return {"record_id": reference.record_id, "status": reference.status,
+            "trust_tier": reference.trust_tier, "run_id": reference.run_id,
+            "metadata": _thaw(reference.metadata)}
+
+
+@dataclass(frozen=True)
+class ReportSnapshot:
+    """Immutable permitted report data and its native binding at read time."""
+
+    backend: BackendDescriptor
+    reference: ReferenceBinding
+    data: Mapping[str, Any]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.backend, BackendDescriptor) or not isinstance(self.reference, ReferenceBinding):
+            raise WorkflowContractError("report snapshot requires native metadata bindings")
+        object.__setattr__(self, "data", _object(self.data, "report snapshot"))
+
+    @property
+    def projection_digest(self) -> str:
+        return contract_digest(self.data)
+
+    def to_dict(self) -> dict:
+        return {"backend": self.backend.to_dict(), "reference": _reference_dict(self.reference),
+                "data": _thaw(self.data)}
+
+
+@dataclass(frozen=True)
+class DecisionContext:
+    """Policy inputs. Construction alone does not authenticate their contents."""
+
+    candidate: ReportSnapshot
+    baseline: ReportSnapshot | None = None
+    comparison: Any = None
+    parameters: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.candidate, ReportSnapshot):
+            raise WorkflowContractError("decision candidate must be ReportSnapshot")
+        if self.baseline is not None and not isinstance(self.baseline, ReportSnapshot):
+            raise WorkflowContractError("decision baseline must be ReportSnapshot")
+        if self.baseline is None and self.comparison is not None:
+            raise WorkflowContractError("a comparison requires a baseline report")
+        object.__setattr__(self, "comparison", _object({"value": self.comparison}, "comparison")["value"])
+        object.__setattr__(self, "parameters", _object(self.parameters, "decision parameters"))
+
+    def to_dict(self) -> dict:
+        return {"candidate": self.candidate.to_dict(),
+                "baseline": self.baseline.to_dict() if self.baseline else None,
+                "comparison": _thaw(self.comparison), "parameters": _thaw(self.parameters)}
+
+    @property
+    def context_digest(self) -> str:
+        return contract_digest(self.to_dict())
+
+
+@dataclass(frozen=True)
+class DecisionOutcome:
+    """An explicit domain outcome and optional binary CI decision.
+
+    None means the policy did not establish a binary pass/fail result. There is
+    no default threshold, aggregation, comparison interpretation, or pass state.
+    """
+
+    outcome: str
+    passed: bool | None
+    reason: str
+    details: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        _text(self.outcome, "outcome")
+        _text(self.reason, "reason")
+        if self.passed is not None and type(self.passed) is not bool:
+            raise WorkflowContractError("passed must be boolean or None")
+        object.__setattr__(self, "details", _object(self.details, "decision details"))
+
+    def to_dict(self) -> dict:
+        return {"outcome": self.outcome, "passed": self.passed,
+                "reason": self.reason, "details": _thaw(self.details)}
+
+
+def _markdown(value: str) -> str:
+    inline = " ".join(value.splitlines())
+    return re.sub(r"([\\`*_{}\[\]()#+.!|~=\-])", r"\\\1", html.escape(inline, quote=False))
+
+
+@dataclass(frozen=True)
+class Verdict:
+    """A policy-bound result with read-only JSON, Markdown and CI projections."""
+
+    policy: CallbackDefinition
+    context: DecisionContext
+    result: DecisionOutcome
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.policy, CallbackDefinition) or self.policy.kind != "decision":
+            raise WorkflowContractError("verdict requires a decision policy definition")
+        if not isinstance(self.context, DecisionContext) or not isinstance(self.result, DecisionOutcome):
+            raise WorkflowContractError("verdict requires decision context and outcome")
+
+    @property
+    def ci_exit_code(self) -> int:
+        """0 for explicit pass, 1 for explicit failure, 2 for undetermined."""
+        return 2 if self.result.passed is None else (0 if self.result.passed else 1)
+
+    def to_dict(self) -> dict:
+        def identity(snapshot):
+            if snapshot is None:
+                return None
+            return {"backend_id": snapshot.backend.backend_id,
+                    "backend_digest": snapshot.backend.descriptor_digest,
+                    "reference": _reference_dict(snapshot.reference),
+                    "projection_digest": snapshot.projection_digest}
+
+        return {"schema_version": "sphynx.verdict.v1", "policy": self.policy.to_dict(),
+                "context_digest": self.context.context_digest,
+                "candidate": identity(self.context.candidate), "baseline": identity(self.context.baseline),
+                "parameters": _thaw(self.context.parameters), "result": self.result.to_dict(),
+                "ci_exit_code": self.ci_exit_code}
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False)
+
+    def to_markdown(self) -> str:
+        state = {True: "Requirements met", False: "Requirements not met", None: "Undetermined"}[self.result.passed]
+        lines = ["## Verdict", "", "- Decision: " + state,
+                 "- Outcome: " + _markdown(self.result.outcome),
+                 "- Policy: " + _markdown(self.policy.callback_id) + " @ " + _markdown(self.policy.version),
+                 "- Candidate grading: " + _markdown(self.context.candidate.reference.record_id or "unidentified"),
+                 "- Trust tier: " + _markdown(self.context.candidate.reference.trust_tier), ""]
+        lines.extend("> " + _markdown(line) for line in self.result.reason.splitlines())
+        return "\n".join(lines) + "\n"
+
+
+def _snapshot(report: Report) -> ReportSnapshot:
+    from .workflows import _reference
+
+    data = report.to_dict()  # Native backend verifies and authorizes this projection.
+    backend = report._backend()
+    return ReportSnapshot(backend.descriptor, _reference(backend, report.native_ref, "grading"), data)
+
+
+def decide_report(report: Report, policy_id: str, *, baseline: Report | None = None,
+                  parameters: Mapping[str, Any] | None = None) -> Verdict:
+    """Explicitly invoke a registered synchronous decision policy once.
+
+    Optional comparison uses Report.compare and keeps the backend's JSON meaning.
+    Opaque comparison objects need a backend-supplied to_dict projection. The
+    policy owns compatibility, population, missingness and domain decision rules.
+    Exceptions remain errors; no successful verdict is manufactured from them.
+    """
+    from .workflows import Report
+
+    if not isinstance(report, Report) or (baseline is not None and not isinstance(baseline, Report)):
+        raise WorkflowContractError("decision inputs must be shared Report values")
+    registry = report.registry
+    assert registry is not None
+    definition = registry.get_policy(policy_id, kind="decision")
+    callback = registry.get_policy_callable(policy_id, kind="decision")
+    if inspect.iscoroutinefunction(callback):
+        raise DecisionPolicyError("decision callbacks must be synchronous")
+    parameters = _object({} if parameters is None else parameters, "decision parameters")
+    comparison = report.compare(baseline) if baseline is not None else None
+    if callable(getattr(comparison, "to_dict", None)):
+        comparison = comparison.to_dict()
+    context = DecisionContext(_snapshot(report), _snapshot(baseline) if baseline is not None else None,
+                              comparison, parameters)
+    context_digest = context.context_digest
+    try:
+        result = callback(context)
+    except Exception as exc:
+        raise DecisionPolicyError("selected decision policy failed") from exc
+    if inspect.iscoroutine(result):
+        result.close()
+    if not isinstance(result, DecisionOutcome):
+        raise DecisionPolicyError("decision callback must return DecisionOutcome")
+    if context.context_digest != context_digest:
+        raise DecisionPolicyError("decision callback modified its input snapshot")
+    if (registry.get_policy(policy_id, kind="decision") != definition or
+            registry.get_policy_callable(policy_id, kind="decision") is not callback):
+        raise DecisionPolicyError("decision policy binding changed during execution")
+    return Verdict(definition, context, result)

sphynx/workflow_defaults.py

@@ -0,0 +1,16 @@
+"""Explicit built-in workflow bootstrap, separate from shared orchestration.
+
+The factory imports the enabled adapter lazily and returns a fresh operator
+registry. Importing this module neither reads case assets nor executes candidate,
+evaluator, reference, policy, or projection callbacks.
+"""
+from __future__ import annotations
+
+from .workflow_registry import WorkflowRegistry
+
+
+def default_workflow_registry() -> WorkflowRegistry:
+    """Create the default extension bindings without a global mutable store."""
+    from .rerank_workflow import build_rerank_registry
+
+    return build_rerank_registry()

sphynx/workflow_extensions.py

@@ -0,0 +1,212 @@
+"""Discover installed extension metadata, then explicitly enable reviewed code.
+
+An installed distribution can include ``sphynx_extensions.json`` in its dist-info
+directory and entry points in the ``sphynx.extensions`` group. Discovery never
+loads entry points. An operator must approve the descriptor digest before
+activation. The digest pins metadata; it does not authenticate package code.
+Only enable packages whose installed code the operator already trusts.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from importlib import metadata
+from typing import Any
+
+from .workflow_contracts import (
+    WorkflowContractError, _object, _text, _texts, _thaw, contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+_MANIFEST = "sphynx_extensions.json"
+_GROUP = "sphynx.extensions"
+_CONTRACT = "sphynx.workflow.v2"
+_FACTORY = re.compile(r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*:[A-Za-z_]\w*\Z", re.ASCII)
+_ROLES = {
+    "backends": ("list_backends", "backend_id"),
+    "schemas": ("list_schemas", "schema_id"),
+    "datasets": ("list_datasets", "dataset_id"),
+    "providers": ("list_providers", "provider_id"),
+    "criteria": ("list_criteria", "criterion_id"),
+    "evaluators": ("list_evaluators", "evaluator_id"),
+    "metrics": ("list_metrics", "metric_id"),
+    "suites": ("list_suites", "suite_id"),
+    "policies": ("list_policies", "callback_id"),
+    "projections": ("list_projections", "callback_id"),
+}
+
+
+class ExtensionError(WorkflowContractError):
+    """An installed extension is malformed, unapproved or incompatible."""
+
+
+def _strict_json(raw: str) -> dict[str, Any]:
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ExtensionError("duplicate extension manifest field")
+            result[key] = value
+        return result
+    if type(raw) is not str or len(raw.encode("utf-8")) > 1_048_576:
+        raise ExtensionError("extension manifest must be UTF-8 JSON of at most 1 MiB")
+    try:
+        value = json.loads(raw, object_pairs_hook=pairs,
+                           parse_constant=lambda value: (_ for _ in ()).throw(ValueError(value)))
+    except (ValueError, TypeError) as exc:
+        raise ExtensionError(f"invalid extension manifest: {exc}") from None
+    if not isinstance(value, dict):
+        raise ExtensionError("extension manifest must be an object")
+    return value
+
+
+@dataclass(frozen=True)
+class PackagedExtension:
+    """Installed metadata snapshot. This descriptor grants no execution trust."""
+
+    extension_id: str
+    version: str
+    implementation_id: str
+    distribution: str
+    distribution_version: str
+    entry_point: str
+    factory: str
+    contract_version: str
+    capabilities: tuple[str, ...] = ()
+    required_capabilities: tuple[str, ...] = ()
+    registrations: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    _installed_distribution: Any = field(default=None, repr=False, compare=False)
+
+    def __post_init__(self):
+        for name in ("extension_id", "version", "implementation_id", "distribution",
+                     "distribution_version", "entry_point", "factory", "contract_version"):
+            _text(getattr(self, name), name)
+        if "." not in self.extension_id and ":" not in self.extension_id:
+            raise ExtensionError("extension_id must be namespaced")
+        if not _FACTORY.fullmatch(self.factory):
+            raise ExtensionError("factory must be an exact module:callable entry point without extras")
+        for name in ("capabilities", "required_capabilities"):
+            object.__setattr__(self, name, _texts(getattr(self, name), name, namespaced=True))
+        if not isinstance(self.registrations, Mapping) or set(self.registrations) - set(_ROLES):
+            raise ExtensionError("registrations contains an unknown registry role")
+        normalized = {role: list(_texts(values, role)) for role, values in self.registrations.items()}
+        object.__setattr__(self, "registrations", _object(normalized, "registrations"))
+        object.__setattr__(self, "metadata", _object(self.metadata, "metadata"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema_version": "sphynx.packaged-extension.v1",
+                **{name: getattr(self, name) for name in (
+                    "extension_id", "version", "implementation_id", "distribution",
+                    "distribution_version", "entry_point", "factory", "contract_version")},
+                "capabilities": list(self.capabilities),
+                "required_capabilities": list(self.required_capabilities),
+                "registrations": _thaw(self.registrations), "metadata": _thaw(self.metadata)}
+
+    @property
+    def descriptor_digest(self) -> str:
+        return contract_digest(self.to_dict())
+
+
+def _from_distribution(dist: Any) -> tuple[PackagedExtension, ...]:
+    raw = dist.read_text(_MANIFEST)
+    if raw is None:
+        return ()
+    manifest = _strict_json(raw)
+    if set(manifest) != {"schema_version", "extensions"} or manifest["schema_version"] != "sphynx.extensions.v1":
+        raise ExtensionError("unsupported extension manifest envelope")
+    rows = manifest["extensions"]
+    if not isinstance(rows, list) or not rows:
+        raise ExtensionError("extensions must be a nonempty array")
+    entries = {}
+    for ep in dist.entry_points:
+        if ep.group != _GROUP:
+            continue
+        if ep.name in entries:
+            raise ExtensionError("duplicate extension entry point")
+        entries[ep.name] = ep
+    result = []
+    required = {"extension_id", "version", "implementation_id", "entry_point", "contract_version", "registrations"}
+    optional = {"capabilities", "required_capabilities", "metadata"}
+    for row in rows:
+        if not isinstance(row, dict) or not required <= row.keys() or row.keys() - required - optional:
+            raise ExtensionError("invalid extension descriptor fields")
+        ep = entries.get(row["entry_point"])
+        if ep is None:
+            raise ExtensionError("extension has no unique installed entry point")
+        result.append(PackagedExtension(**row, distribution=dist.metadata["Name"],
+                                       distribution_version=dist.version, factory=ep.value,
+                                       _installed_distribution=dist))
+    if len({item.extension_id for item in result}) != len(result):
+        raise ExtensionError("duplicate extension ID in distribution")
+    return tuple(result)
+
+
+def discover_extensions(*, distributions: Iterable[Any] | None = None) -> tuple[PackagedExtension, ...]:
+    """Read installed metadata only. Never import or load a factory.
+
+    ``distributions`` permits explicit installed-environment inventories and
+    offline tests. Malformed or duplicate declarations fail visibly.
+    """
+    selected = metadata.distributions() if distributions is None else distributions
+    result = [item for dist in selected for item in _from_distribution(dist)]
+    if len({item.extension_id for item in result}) != len(result):
+        raise ExtensionError("duplicate installed extension ID; select an unambiguous environment")
+    return tuple(sorted(result, key=lambda item: item.extension_id))
+
+
+def _membership(registry: WorkflowRegistry) -> dict[str, set[str]]:
+    return {role: {getattr(item, identifier) for item in getattr(registry, method)()}
+            for role, (method, identifier) in _ROLES.items()}
+
+
+def enable_extension(extension: PackagedExtension, registry: WorkflowRegistry, *,
+                     approved_digest: str) -> WorkflowRegistry:
+    """Explicitly load trusted installed code into a staged registry.
+
+    Approve a reviewed descriptor digest, then use the returned registry. The
+    original registration stores remain unchanged if activation fails. Trusted
+    factory side effects and shared implementation state are not sandboxed.
+    Factories accept one registry, register exactly their declared additions,
+    and return None. Candidate-supplied import strings are not accepted here.
+    """
+    if not isinstance(extension, PackagedExtension) or not isinstance(registry, WorkflowRegistry):
+        raise ExtensionError("enable_extension requires discovered metadata and WorkflowRegistry")
+    if extension.descriptor_digest != approved_digest:
+        raise ExtensionError("extension descriptor has not been approved")
+    if extension.contract_version != _CONTRACT:
+        raise ExtensionError("extension requires an unsupported workflow contract")
+    dist = extension._installed_distribution
+    if dist is None:
+        raise ExtensionError("extension must come from an installed distribution inventory")
+    current = [item for item in _from_distribution(dist) if item.extension_id == extension.extension_id]
+    if len(current) != 1 or current[0].descriptor_digest != approved_digest:
+        raise ExtensionError("installed extension metadata changed after review")
+    available = {cap for backend in registry.list_backends() for cap in backend.capabilities}
+    if not set(extension.required_capabilities) <= available:
+        raise ExtensionError("extension requires unavailable backend capabilities")
+    entries = [ep for ep in dist.entry_points if ep.group == _GROUP and ep.name == extension.entry_point]
+    if len(entries) != 1 or entries[0].value != extension.factory:
+        raise ExtensionError("installed extension factory changed after review")
+    staged = registry.fork()
+    before = _membership(staged)
+    factory = entries[0].load()
+    if not callable(factory):
+        raise ExtensionError("installed extension factory is not callable")
+    if factory(staged) is not None:
+        raise ExtensionError("extension factory must register into its supplied registry and return None")
+    after = _membership(staged)
+    for role in _ROLES:
+        expected = set(extension.registrations.get(role, ()))
+        if after[role] - before[role] != expected or not before[role] <= after[role]:
+            raise ExtensionError(f"extension registered unexpected {role}")
+    provided = {cap for backend in staged.list_backends()
+                if backend.backend_id not in before["backends"] for cap in backend.capabilities}
+    if not set(extension.capabilities) <= provided:
+        raise ExtensionError("extension did not register its declared capabilities")
+    for suite in staged.list_suites():
+        staged.resolve_suite(suite.suite_id)
+    staged.fork()  # Recheck validator/provider/backend pins after trusted factory execution.
+    return staged