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

sphynx/pipeline_workflow.py

@@ -0,0 +1,551 @@
+"""Common workflow adapter for native source-bound RAG pipeline execution.
+
+The existing v1 runner, artifacts, references, grader and comparison remain the
+authority. This adapter supports explicit manifest-bound replacements and reads
+permitted stage projections. Its native attempts are a fixed grid, not retries.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+from typing import Any
+
+from .assessment_contracts import Assessment, CaseView, EvidenceView
+from .components import (
+    AdapterDescriptor, BatchConfiguration, ComponentManifest, ComponentRef, ComponentRegistry,
+    EvaluationTarget, OPERATIONS_BY_KIND, PIPELINE_COMPONENT_ORDER,
+    adapter_component_identity_sha256, manifest_validate_selected_models,
+)
+from .dataset_v3 import load_dataset_v3
+from .integration_contracts import CandidateConfiguration, TrackEvaluationRef, TrackRunRef, value_digest
+from .pipeline import (
+    GRADER_RELEASE, INTERFACE, METRIC_RELEASE, STAGES, _policy, _score, _verified,
+    build_pipeline_request, _compare_report_data, grade_pipeline, report_pipeline,
+    run_pipeline, validate_pipeline_response,
+)
+from ._composed_pipeline import compose_pipeline
+from ._pipeline_core import CHANGE_COMPONENTS, _flatten
+from ._track_capture import read_artifact, verify_track_evaluation
+from .chunking import _documents, _select_tasks, _verify_approval
+from .stage_contracts import (
+    STAGE_EVIDENCE_CAPABILITY, StageContractError, StageDefinition, StageEvidence,
+    StageReplacement, StageSelector,
+)
+from .workflow_contracts import (
+    AdmissionBinding, BackendDescriptor, Criterion, Dataset, DatasetDefinition,
+    EvaluatorDefinition, MetricSpec, PayloadSchema, ReferenceBinding, ResolvedBinding,
+    SuiteDefinition, WorkflowContractError, _text, _thaw, contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+_KINDS = PIPELINE_COMPONENT_ORDER
+_GROUPS = dict(zip(_KINDS, ("chunking", "embedding", "retrieval", "reranker", "fusion", "dedup", "gating")))
+_TARGET = EvaluationTarget("level2", "pipeline")
+_CASE_SCHEMA = "sphynx.pipeline.case-input.v1"
+_ROW_FIELDS = {
+    "candidate_id", "chunk_id", "document_id", "start", "end", "text", "input", "input_sha256",
+    "embedding", "dense_rank", "dense_score", "reranker_rank", "reranker_score",
+    "fusion_rank", "fusion_score", "dedup_decision", "post_dedup_rank",
+    "gate_decision", "gate_threshold", "final_rank",
+}
+_METRICS = tuple(f"sphynx.pipeline.{stage}.{metric}" for stage in STAGES
+                 for metric in ("candidate_count", "recall_at_5", "ndcg_at_5", "mrr"))
+_EVALUATOR = "sphynx.pipeline.native-grader.v1"
+_AGGREGATION = "sphynx.pipeline.native-aggregation.v1"
+_COMPARISON = "sphynx.pipeline.native-comparison.v1"
+
+
+def stage_schema_id(kind, direction):
+    return f"sphynx.pipeline.{kind}.{direction}.v1"
+
+
+def _rows(value, name):
+    if type(value) is not list or any(type(row) is not dict for row in value):
+        raise WorkflowContractError(name + " must contain JSON objects")
+    return value
+
+
+def _validate_case(value):
+    if type(value) is not dict or set(value) != {"case_id", "query", "conversation_context", "documents"}:
+        raise WorkflowContractError("pipeline case input fields differ")
+    _text(value["case_id"], "case_id")
+    _text(value["query"], "query")
+    _rows(value["documents"], "documents")
+
+
+def validate_stage_input(kind, value):
+    if kind not in _KINDS or type(value) is not dict:
+        raise WorkflowContractError("unsupported pipeline stage input")
+    expected = ({"task_id", "documents"} if kind == "chunker" else {"items"} if kind == "embedder"
+                else {"task_id", "query", "query_embedding", "candidates"}
+                if kind in {"retriever", "reranker", "fusion"} else {"task_id", "query", "candidates"})
+    if set(value) != expected:
+        raise WorkflowContractError("pipeline stage input fields differ")
+    if "task_id" in value:
+        _text(value["task_id"], "task_id")
+    if "query" in value:
+        _text(value["query"], "query")
+    if kind == "chunker":
+        for row in _rows(value["documents"], "documents"):
+            if not {"document_id", "text"} <= set(row) or not set(row) <= {
+                    "document_id", "text", "content_sha256", "document_revision_family_id"}:
+                raise WorkflowContractError("pipeline document input fields differ")
+            _text(row["document_id"], "document_id")
+            _text(row["text"], "document text")
+    else:
+        for row in _rows(value["items" if kind == "embedder" else "candidates"], "stage rows"):
+            if "candidate_id" not in row or not set(row) <= _ROW_FIELDS:
+                raise WorkflowContractError("pipeline candidate input fields differ")
+
+
+def validate_stage_output(kind, value):
+    if kind not in _KINDS or type(value) is not dict:
+        raise WorkflowContractError("unsupported pipeline stage output")
+    key = "chunks" if kind == "chunker" else "embeddings" if kind == "embedder" else "candidates"
+    allowed = {key, "latency_ms"} | ({"selected_candidate_ids"} if kind == "gate" else set())
+    if key not in value or not set(value) <= allowed:
+        raise WorkflowContractError("pipeline stage output fields differ")
+    for row in _rows(value[key], "stage output rows"):
+        fields = {"candidate_id", "vector"} if kind == "embedder" else _ROW_FIELDS
+        if not set(row) <= fields:
+            raise WorkflowContractError("pipeline stage output has unapproved fields")
+    # PayloadSchema additionally checks finite JSON and immutable content.
+
+
+def _stage_definition(component):
+    return StageDefinition(
+        component.kind, component.implementation.implementation_id, component.version,
+        stage_schema_id(component.kind, "input"), stage_schema_id(component.kind, "output"),
+        "sha256:" + component.implementation.artifact_sha256, "sha256:" + component.config_sha256,
+        metadata={"component_id": component.component_id,
+                  "descriptor_digest": "sha256:" + adapter_component_identity_sha256(
+                      AdapterDescriptor.from_component(component))},
+    )
+
+
+@dataclass(frozen=True)
+class PipelineSource:
+    """Operator-provided metadata; constructing it does not read dataset bytes."""
+
+    path: Path = field(repr=False, compare=False)
+    sha256: str
+    dataset_id: str
+    version: str
+    case_ids: tuple[str, ...]
+
+    def __post_init__(self):
+        object.__setattr__(self, "path", Path(self.path))
+        for name in ("dataset_id", "version"):
+            _text(getattr(self, name), name)
+        from .integration_contracts import require_digest
+        require_digest(self.sha256, "dataset sha256")
+        if isinstance(self.case_ids, (str, bytes)) or not self.case_ids:
+            raise WorkflowContractError("pipeline source needs an ordered case cohort")
+        ids = tuple(_text(value, "case_id") for value in self.case_ids)
+        if len(ids) != len(set(ids)):
+            raise WorkflowContractError("pipeline source has duplicate cases")
+        object.__setattr__(self, "case_ids", ids)
+
+    def to_dict(self):
+        return {"sha256": self.sha256, "dataset_id": self.dataset_id,
+                "version": self.version, "case_ids": list(self.case_ids)}
+
+
+@dataclass(frozen=True)
+class PipelineCandidate:
+    """Pinned component configuration and caller-declared revision; not attestation."""
+
+    configuration: BatchConfiguration
+    revision: str
+    replacement: StageReplacement | None = None
+
+    def __post_init__(self):
+        if not isinstance(self.configuration, BatchConfiguration):
+            raise WorkflowContractError("pipeline candidate needs a BatchConfiguration")
+        _text(self.revision, "candidate revision")
+        if self.replacement is not None and not isinstance(self.replacement, StageReplacement):
+            raise WorkflowContractError("pipeline replacement must be StageReplacement")
+
+
+class PipelineReport:
+    def __init__(self, data):
+        self._data = json.loads(json.dumps(data, ensure_ascii=False, allow_nan=False))
+
+    def to_dict(self):
+        return json.loads(json.dumps(self._data, ensure_ascii=False))
+
+    def to_json(self):
+        return json.dumps(self._data, ensure_ascii=False, sort_keys=True, allow_nan=False)
+
+    def to_markdown(self):
+        metrics = self._data["metrics"]
+        lines = ["# Pipeline report", "", f"Grading pass: {self._data['evaluation_id']}", "",
+                 f"Coverage: {metrics['coverage']}", "", "| Stage | nDCG@5 | Recall@5 | MRR |",
+                 "| --- | --- | --- | --- |"]
+        for stage, values in metrics["stage_metrics"].items():
+            lines.append("| " + stage + " | " + " | ".join(
+                "unavailable" if values[key] is None else str(values[key])
+                for key in ("ndcg_at_5", "recall_at_5", "mrr")) + " |")
+        return "\n".join(lines)
+
+
+class PipelineBackend:
+    """Native fixed-grid subsystem execution with explicit component replacement."""
+
+    def __init__(self, source: PipelineSource, component_manifest: ComponentManifest,
+                 baseline_configuration: BatchConfiguration, component_registry: ComponentRegistry, *,
+                 suite_id="rag.pipeline.v1", synthetic=False, owner_authorized=False,
+                 pack_manifest_path=None, allowed_implementation_kinds=("builtin", "recorded"),
+                 trials=1, attempts=1):
+        if not isinstance(source, PipelineSource) or not isinstance(component_manifest, ComponentManifest):
+            raise WorkflowContractError("pipeline backend requires source and component manifest")
+        if not isinstance(component_registry, ComponentRegistry) or component_registry.manifest.sha256 != component_manifest.sha256:
+            raise WorkflowContractError("pipeline registry differs from its manifest")
+        if type(synthetic) is not bool or type(owner_authorized) is not bool:
+            raise WorkflowContractError("pipeline authorization flags must be boolean")
+        for number in (trials, attempts):
+            if type(number) is not int or number < 1:
+                raise WorkflowContractError("native fixed-grid counts must be positive integers")
+        _text(suite_id, "suite_id")
+        self.source, self.components, self.baseline, self.adapters = source, component_manifest, baseline_configuration, component_registry
+        self.synthetic, self.owner_authorized = synthetic, owner_authorized
+        self.pack_manifest_path = None if pack_manifest_path is None else Path(pack_manifest_path)
+        self.allowed_implementation_kinds = tuple(allowed_implementation_kinds)
+        if (not self.allowed_implementation_kinds
+                or len(set(self.allowed_implementation_kinds)) != len(self.allowed_implementation_kinds)
+                or set(self.allowed_implementation_kinds) - {"builtin", "recorded", "command"}):
+            raise WorkflowContractError("pipeline implementation permissions must be explicit supported kinds")
+        self.trials, self.attempts, self.suite_id = trials, attempts, suite_id
+        self._configuration(baseline_configuration)
+        metadata = {"source": source.to_dict(), "component_manifest_digest": "sha256:" + component_manifest.sha256,
+                    "baseline": self._configuration(baseline_configuration), "synthetic": synthetic,
+                    "owner_authorized": owner_authorized, "pack_manifest_provided": pack_manifest_path is not None,
+                    "fixed_grid": {"trials": trials, "attempts": attempts, "selection": "first_success_per_trial"},
+                    "allowed_implementation_kinds": list(self.allowed_implementation_kinds)}
+        self._metadata_digest = contract_digest(metadata)
+        self._descriptor = BackendDescriptor(
+            "sphynx.pipeline." + suite_id, "v1", "sphynx.pipeline.native-workflow.v1",
+            ("sphynx.pipeline.substitution.v1", STAGE_EVIDENCE_CAPABILITY, "sphynx.saved-assessment.v1"),
+            ("subsystem",), ("local",), (suite_id,), metadata)
+        dataset = DatasetDefinition(
+            source.dataset_id, source.version, suite_id + ".provider", _CASE_SCHEMA,
+            selection={"case_ids": list(source.case_ids), "order": "native_dataset_order"},
+            identity={"sha256": source.sha256, "reference_access": "backend_authorized_native_grader_only"})
+        self._definition = SuiteDefinition(
+            suite_id, "v1", self.descriptor.backend_id, "Native source-bound pipeline",
+            configuration=metadata, criterion_ids=_METRICS, metric_ids=_METRICS,
+            evaluator_ids=(_EVALUATOR,), required_capabilities=("sphynx.pipeline.substitution.v1",),
+            datasets=(dataset,), metadata={"trust_tier": "local_unverified", "candidate_source_bytes_verified": False})
+        self._boundary = contract_digest({"suite": self._definition.to_dict(), "boundary": "composed_source_documents"})
+
+    @property
+    def descriptor(self):
+        self._metadata_unchanged()
+        return self._descriptor
+
+    def _metadata_unchanged(self):
+        current = {"source": self.source.to_dict(), "component_manifest_digest": "sha256:" + self.components.sha256,
+                   "baseline": self._configuration(self.baseline), "synthetic": self.synthetic,
+                   "owner_authorized": self.owner_authorized, "pack_manifest_provided": self.pack_manifest_path is not None,
+                   "fixed_grid": {"trials": self.trials, "attempts": self.attempts, "selection": "first_success_per_trial"},
+                   "allowed_implementation_kinds": list(self.allowed_implementation_kinds)}
+        if contract_digest(current) != self._metadata_digest:
+            raise WorkflowContractError("pipeline backend policy/identity drift")
+
+    def describe(self, suite_id):
+        if suite_id != self.suite_id:
+            raise WorkflowContractError("pipeline suite is not registered by this backend")
+        return self._definition
+
+    def _configuration(self, configuration):
+        if not isinstance(configuration, BatchConfiguration) or set(configuration.by_kind) != set(_KINDS):
+            raise WorkflowContractError("pipeline configuration requires exactly seven component kinds")
+        selected = {}
+        raw = {item["component_id"]: item for item in self.components.value["components"]}
+        for ref in configuration.components:
+            component = self.components.by_id.get(ref.component_id)
+            if component is None or ComponentRef(component.kind, component.component_id, component.version, component.config_sha256) != ref:
+                raise WorkflowContractError("pipeline component reference differs from manifest")
+            if _TARGET not in component.capabilities:
+                raise WorkflowContractError("pipeline component lacks subsystem capability")
+            selected[ref.kind] = raw[ref.component_id]
+        manifest_validate_selected_models((configuration,), self.components.by_id)
+        return selected
+
+    def baseline_candidate(self, *, revision):
+        return PipelineCandidate(self.baseline, revision)
+
+    def replace(self, stage_id, component_id, *, configuration_id, revision):
+        if stage_id not in _KINDS:
+            raise StageContractError("unknown native pipeline stage")
+        component = self.components.by_id.get(component_id)
+        if component is None or component.kind != stage_id:
+            raise StageContractError("replacement component has an incompatible kind")
+        before = self.components.by_id[self.baseline.by_kind[stage_id].component_id]
+        change = StageReplacement(stage_id, _stage_definition(before), _stage_definition(component))
+        refs = tuple(ComponentRef(component.kind, component.component_id, component.version, component.config_sha256)
+                     if ref.kind == stage_id else ref for ref in self.baseline.components)
+        configuration = BatchConfiguration(configuration_id, refs)
+        self._configuration(configuration)
+        return PipelineCandidate(configuration, revision, change)
+
+    def _candidate(self, candidate):
+        if not isinstance(candidate, PipelineCandidate):
+            raise WorkflowContractError("pipeline candidate must be PipelineCandidate")
+        selected = self._configuration(candidate.configuration)
+        changes = [kind for kind in _KINDS if self.baseline.by_kind[kind] != candidate.configuration.by_kind[kind]]
+        if changes:
+            change = candidate.replacement
+            if change is None or changes != [change.stage_id]:
+                raise StageContractError("candidate changes differ from the explicit replacement")
+            change.require_baseline(_stage_definition(self.components.by_id[self.baseline.by_kind[change.stage_id].component_id]))
+            if change.replacement != _stage_definition(self.components.by_id[candidate.configuration.by_kind[change.stage_id].component_id]):
+                raise StageContractError("replacement component identity drift")
+        elif candidate.replacement is not None:
+            raise StageContractError("declared replacement did not occur")
+        controlled = {_GROUPS[kind]: selected[kind] for kind in _KINDS}
+        controlled["top_k"] = self.components.by_id[candidate.configuration.by_kind["gate"].component_id].config.get("top_k", 5)
+        return CandidateConfiguration(
+            candidate.configuration.configuration_id, INTERFACE, value_digest(selected),
+            {"controlled_config": controlled, "workflow_binding": self._definition.definition_digest,
+             "candidate_revision": candidate.revision,
+             "replacement": None if candidate.replacement is None else candidate.replacement.to_dict()}, "trusted_local")
+
+    def _authorize(self):
+        self._metadata_unchanged()
+        if not self.synthetic and (not self.owner_authorized or self.pack_manifest_path is None):
+            raise PermissionError("pipeline source/reference access requires explicit owner authorization and pack manifest")
+
+    def _loaded(self):
+        self._authorize()
+        dataset = load_dataset_v3(self.source.path, expected_sha256=self.source.sha256)
+        if (dataset.dataset_id, dataset.version) != (self.source.dataset_id, self.source.version):
+            raise WorkflowContractError("pipeline source metadata differs from verified dataset")
+        tasks = _select_tasks(dataset, self.source.case_ids)
+        if tuple(task["task_id"] for task in tasks) != self.source.case_ids:
+            raise WorkflowContractError("pipeline ordered case cohort differs")
+        return dataset, tasks
+
+    def cases(self, suite):
+        if suite.definition_digest != self._definition.definition_digest:
+            raise WorkflowContractError("pipeline suite identity drift")
+        _, tasks = self._loaded()
+        schema = PayloadSchema(_CASE_SCHEMA, "v1", "sphynx.pipeline.case-validator.v1", _validate_case)
+        return tuple(CaseView.validated(task["task_id"],
+            {"case_id": task["task_id"], "query": task["query"], "conversation_context": task["conversation_context"],
+             "documents": _documents(task)}, schema=schema) for task in tasks)
+
+    def _selected(self, plan):
+        if plan.suite.definition_digest != self._definition.definition_digest or plan.scope != "subsystem" or plan.mode != "local":
+            raise WorkflowContractError("pipeline requires its registered local subsystem suite")
+        if plan.parameters or plan.runtime:
+            raise WorkflowContractError("legacy pipeline controls are fixed in backend metadata; runtime overrides unsupported")
+        return self._candidate(plan.candidate)
+
+    def resolve(self, plan):
+        candidate = self._selected(plan)
+        return ResolvedBinding({"backend": self.descriptor.to_dict(), "suite": self._definition.to_dict(),
+                                "candidate": candidate.to_dict(), "scope": plan.scope, "mode": plan.mode},
+                               native_ref=candidate)
+
+    def admit(self, plan, resolved):
+        expected = self.resolve(plan)
+        if resolved.resolution_digest != expected.resolution_digest:
+            raise WorkflowContractError("pipeline resolution identity drift")
+        dataset, tasks = self._loaded()
+        candidate = self._selected(plan)
+        policy = _policy(dataset, self.source.sha256, candidate, boundary="composed_source_documents",
+                         synthetic=self.synthetic, owner_authorized=self.owner_authorized,
+                         pack_manifest_path=self.pack_manifest_path, trials=self.trials,
+                         attempts=self.attempts, boundary_digest=self._boundary)
+        observed = {"approved_manifest_source": None if self.synthetic else self.pack_manifest_path.read_text(encoding="utf-8")}
+        _verify_approval(dataset, self.source.sha256, policy, observed)
+        descriptors = []
+        for ref in plan.candidate.configuration.components:
+            component = self.components.by_id[ref.component_id]
+            if component.implementation.kind not in self.allowed_implementation_kinds:
+                raise PermissionError("pipeline component implementation kind is not authorized")
+            adapter = self.adapters.resolve(ref.component_id, _TARGET, OPERATIONS_BY_KIND[ref.kind][0])
+            if adapter.descriptor != AdapterDescriptor.from_component(component):
+                raise WorkflowContractError("pipeline adapter identity drift")
+            descriptors.append(_stage_definition(component).to_dict())
+        return AdmissionBinding(resolved.resolution_digest,
+            {"dataset_digest": self.source.sha256, "case_ids": [task["task_id"] for task in tasks],
+             "stages": descriptors, "policy_digest": value_digest(policy)}, "local_unverified", True, False)
+
+    def recheck(self, plan, resolved, admission):
+        if admission.to_dict() != self.admit(plan, resolved).to_dict():
+            raise WorkflowContractError("pipeline admission facts changed")
+
+    def execute(self, plan, resolved, admission, output_dir):
+        self.recheck(plan, resolved, admission)
+        if output_dir is None:
+            raise WorkflowContractError("native pipeline requires an output directory")
+        def invoke(kind, operation, payload):
+            validate_stage_input(kind, payload)
+            ref = plan.candidate.configuration.by_kind[kind]
+            output = self.adapters.resolve(ref.component_id, _TARGET, operation).invoke(operation, payload)
+            validate_stage_output(kind, output)
+            return output
+        return run_pipeline(self._selected(plan), lambda request: compose_pipeline(request, invoke),
+            self.source.path, output_dir, expected_sha256=self.source.sha256,
+            synthetic=self.synthetic, owner_authorized=self.owner_authorized,
+            pack_manifest_path=self.pack_manifest_path, trials=self.trials, attempts=self.attempts,
+            case_ids=self.source.case_ids, boundary_digest=self._boundary, boundary="composed_source_documents")
+
+    def accepts_reference(self, native_ref, kind):
+        return isinstance(native_ref, TrackRunRef if kind == "run" else TrackEvaluationRef) if kind in {"run", "grading"} else False
+
+    def _run(self, native_ref):
+        self._authorize()
+        run = native_ref.run if isinstance(native_ref, TrackEvaluationRef) else native_ref
+        if not isinstance(run, TrackRunRef):
+            raise WorkflowContractError("pipeline needs a native TrackRunRef")
+        manifest, tasks, policy, requests = _verified(run, self.source.path, self.source.sha256)
+        if (manifest.identity.subject_digest != self._boundary
+                or manifest.candidate.parameters.get("workflow_binding") != self._definition.definition_digest
+                or manifest.case_ids != self.source.case_ids):
+            raise WorkflowContractError("native run belongs to a different pipeline binding")
+        return run, manifest, tasks, policy, requests
+
+    def reference(self, native_ref, kind):
+        if not self.accepts_reference(native_ref, kind):
+            raise WorkflowContractError("unsupported native pipeline reference")
+        run, manifest, _, _, _ = self._run(native_ref)
+        if kind == "grading":
+            verified = verify_track_evaluation(native_ref)
+            return ReferenceBinding(verified.evaluation_id, "graded", "local_unverified", run.run_id)
+        status = "completed_with_failures" if any(row.failure for row in manifest.captures) else "completed"
+        return ReferenceBinding(run.run_id, status, "local_unverified", run.run_id)
+
+    def assess(self, native_run):
+        self._run(native_run)
+        return grade_pipeline(native_run, self.source.path, expected_sha256=self.source.sha256)
+
+    def report(self, native_grading):
+        self._run(native_grading)
+        return PipelineReport(report_pipeline(native_grading, self.source.path, expected_sha256=self.source.sha256))
+
+    def assessments(self, native_grading, case_id=None):
+        run, manifest, tasks, _, requests = self._run(native_grading)
+        data = self.report(native_grading).to_dict()
+        if case_id is not None and case_id not in manifest.case_ids:
+            raise StageContractError("case is not in this pipeline report")
+        result = []
+        by_id = {task["task_id"]: task for task in tasks}
+        # Per-attempt diagnostics retain failed attempts. The native report's
+        # aggregate still selects first_success_per_trial, without redefinition.
+        for capture in manifest.captures:
+            if case_id is not None and capture.case_id != case_id:
+                continue
+            score, missing = None, 0
+            if capture.failure is None and capture.response is not None:
+                score, missing = _score(by_id[capture.case_id], read_artifact(run.path, capture.response),
+                                        requests[capture.case_id])
+            for stage in STAGES:
+                for metric in ("candidate_count", "recall_at_5", "ndcg_at_5", "mrr"):
+                    value = None if score is None else score["stage_metrics"][stage][metric]
+                    availability = "available" if value is not None else "undefined" if score is not None else "missing"
+                    reason = (None if value is not None else "native_metric_population_undefined" if score is not None
+                              else "native_labels_missing" if missing else capture.failure or "native_response_missing")
+                    result.append(Assessment(
+                        f"sphynx.pipeline.{stage}.{metric}", _EVALUATOR, capture.case_id, "score",
+                        availability, value=value, reason=reason,
+                        evidence_ids=() if capture.response is None else (capture.response.sha256,),
+                        run_id=run.run_id, grading_id=data["evaluation_id"], trial=capture.trial_index,
+                        attempt=capture.attempt_index))
+        return tuple(result)
+
+    def compare(self, baseline, candidate):
+        return self._comparison_data(baseline, candidate)[1]
+
+    def _comparison_data(self, baseline, candidate):
+        self._run(baseline)
+        self._run(candidate)
+        reports = [self.report(ref).to_dict() for ref in (baseline, candidate)]
+        left, right = (report["metrics"]["controlled_config"] for report in reports)
+        a, b = _flatten(left), _flatten(right)
+        paths = tuple(sorted(key for key in a.keys() | b.keys() if a.get(key) != b.get(key)))
+        groups = {path.split(".", 1)[0] for path in paths}
+        if groups - CHANGE_COMPONENTS:
+            raise StageContractError("native pipeline comparison does not support changes: " + ", ".join(sorted(groups - CHANGE_COMPONENTS)))
+        return reports, _compare_report_data(*reports, declared_paths=paths)
+
+    def compare_view(self, baseline, candidate):
+        from ._comparison_adapters import _pipeline_view, _sources
+        reports, native = self._comparison_data(baseline, candidate)
+        conditions = [{"identity": report["identity"], "controlled_config": report["metrics"]["controlled_config"]}
+                      for report in reports]
+        return _pipeline_view(_sources(self, baseline, candidate, conditions=conditions), native,
+                              {identifier: _metric_spec(identifier) for identifier in _METRICS}, reports)
+
+    def stage_evidence(self, native_ref, selector):
+        if not isinstance(selector, StageSelector):
+            raise StageContractError("stage selection requires StageSelector")
+        if selector.stage_id not in _KINDS or selector.occurrence != 1:
+            raise StageContractError("native pipeline stage/occurrence is unsupported")
+        run, manifest, _, _, requests = self._run(native_ref)
+        if isinstance(native_ref, TrackEvaluationRef):
+            self.report(native_ref)
+        capture = next((row for row in manifest.captures if
+                        (row.case_id, row.trial_index, row.attempt_index) ==
+                        (selector.case_id, selector.trial, selector.attempt)), None)
+        if capture is None:
+            raise StageContractError("stage selector is outside this run's case/trial/attempt cohort")
+        available = capture.failure is None and capture.response is not None
+        evidence = EvidenceView(
+            f"{run.run_id}/{selector.case_id}/{selector.trial}/{selector.attempt}/{selector.stage_id}",
+            None if capture.response is None else capture.response.sha256, "application/json", "stage.output",
+            "native.pipeline.retained_stage_projection", "candidate_permitted",
+            schema_version="sphynx.rag.pipeline.composed.response.v1", case_id=selector.case_id,
+            step_id=selector.stage_id, availability="available" if available else "unavailable",
+            metadata={"artifact_path": None if capture.response is None else capture.response.path,
+                      "projection_path": "/stages/" + selector.stage_id, "run_id": run.run_id,
+                      "trial": selector.trial, "attempt": selector.attempt, "occurrence": 1,
+                      "timing_authority": "component_reported_unattested"})
+        if not available:
+            return (StageEvidence.unavailable(selector, evidence,
+                reason="native_stage_output_not_retained:" + str(capture.failure)),)
+        response = validate_pipeline_response(read_artifact(run.path, capture.response), requests[selector.case_id])
+        projection = response["stages"][selector.stage_id]
+        schema = PayloadSchema(stage_schema_id(selector.stage_id, "output"), "v1",
+                               "sphynx.pipeline.stage-output-validator.v1",
+                               lambda value: validate_stage_output(selector.stage_id, value))
+        return (StageEvidence.projected(selector, evidence, projection, schema=schema),)
+
+
+def _metric_spec(identifier):
+    return MetricSpec(identifier, "v1", "count" if identifier.endswith("candidate_count") else "ratio",
+        "descriptive" if identifier.endswith("candidate_count") else "higher",
+        aggregation_policy=_AGGREGATION, comparison_policy=_COMPARISON,
+        population={"source": "native_per_metric_eligibility_missing_and_undefined"})
+
+
+def register_pipeline_backend(registry: WorkflowRegistry, backend: PipelineBackend):
+    """Enable explicit operator bindings; registration loads no dataset or adapters."""
+    suite = backend.describe(backend.suite_id)
+    registry.register_backend(backend)
+    schema = registry.register_schema(PayloadSchema(_CASE_SCHEMA, "v1", "sphynx.pipeline.case-validator.v1", _validate_case))
+    registry.register_provider(Dataset(suite.datasets[0], schema, lambda selection: backend.cases(suite)))
+    for kind in _KINDS:
+        for direction, validator in (("input", validate_stage_input), ("output", validate_stage_output)):
+            registry.register_schema(PayloadSchema(
+                stage_schema_id(kind, direction), "v1", f"sphynx.pipeline.stage-{direction}-validator.v1",
+                lambda value, kind=kind, validator=validator: validator(kind, value)))
+    registry.register_policy(_AGGREGATION, version="v1", implementation_id=METRIC_RELEASE, kind="aggregation")
+    registry.register_policy(_COMPARISON, version="v1", implementation_id="sphynx.pipeline.compare.v1", kind="comparison")
+    for identifier in _METRICS:
+        registry.register_criterion(Criterion(identifier, "v1", identifier))
+        registry.register_metric(_metric_spec(identifier))
+    registry.register_evaluator(EvaluatorDefinition(_EVALUATOR, "v1", GRADER_RELEASE,
+        criterion_ids=_METRICS, metric_ids=_METRICS, required_capabilities=("sphynx.saved-assessment.v1",)))
+    registry.register_suite(suite)
+    return backend
+
+
+def build_pipeline_registry(backend: PipelineBackend) -> WorkflowRegistry:
+    """Fresh registry with the operator's exact native dataset ID allowed."""
+    registry = WorkflowRegistry(legacy_ids=(backend.source.dataset_id,))
+    register_pipeline_backend(registry, backend)
+    return registry