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

sphynx/lifecycle_workflow.py

@@ -0,0 +1,490 @@
+"""Registered lifecycle drivers through the unchanged common workflow protocol.
+
+Providers validate candidate-permitted cases. Evaluators, reducers, report
+projections and comparisons are explicit operator registrations. No domain,
+numeric reducer, quality threshold or protected-reference grant is implicit.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+import json
+from pathlib import Path
+
+from .assessment_contracts import Assessment, CaseView, EvidenceView, _verified_evaluator_context
+from .lifecycle import (
+    GradingPolicy, LifecycleError, LifecycleGradingRef, LifecycleJournal,
+    LifecycleRunRef, RunPolicy, _driver_admission, _object, _raw, _read_json, _require,
+    _thaw, assess_lifecycle, execute_lifecycle,
+    verify_lifecycle_grading, verify_lifecycle_run,
+)
+from .workflow_contracts import (
+    AdmissionBinding, BackendDescriptor, PlanBinding, ReferenceBinding, ResolvedBinding,
+    ReportProjection, SuiteDefinition, WorkflowContractError, contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+
+class _ComparisonMismatch(LifecycleError, WorkflowContractError):
+    """Native comparison conditions differ; not an evidence/access failure."""
+
+
+def _comparison_require(condition, message):
+    if not condition:
+        raise _ComparisonMismatch(message)
+
+
+class LifecycleProjection:
+    """A permitted explicit projection, without a compulsory numeric layout."""
+    def __init__(self, value, *, context=None):
+        self._value = _object(value, "report projection")
+        self._context = _object(context or {}, "report presentation context")
+
+    def to_dict(self):
+        return _thaw(self._value)
+
+    def to_json(self):
+        return _raw(self._value).decode("utf-8")
+
+    def to_markdown(self):
+        from .report_rendering import lifecycle_markdown
+        return lifecycle_markdown(self.to_dict(), _thaw(self._context))
+
+
+class LifecycleBackend:
+    """An operator-configured WorkflowBackend for versioned lifecycle records.
+
+    Plan parameters can select run_policy, grading_policy and serialized
+    resume/reuse references. References are local owner-readable records. Only
+    an explicit admission_verifier can claim external asset/source verification.
+    """
+    def __init__(self, registry, suite, *, driver, evaluator_id, projection_schema_id,
+                 comparison_policy_id, run_policy=None, grading_policy=None,
+                 reference_access=None, admission_verifier=None, scopes=("component",),
+                 modes=("local",), capabilities=(), evaluator_binding=None, report_binding=None,
+                 include_emitted_evidence=False):
+        _require(isinstance(registry, WorkflowRegistry) and isinstance(suite, SuiteDefinition),
+                 "lifecycle backend requires registry and suite")
+        _require(evaluator_id in suite.evaluator_ids, "lifecycle evaluator must be declared by the suite")
+        self.registry, self.suite, self.driver = registry, suite, driver
+        self.evaluator_id, self.projection_schema_id = evaluator_id, projection_schema_id
+        self.comparison_policy_id = comparison_policy_id
+        self.run_policy, self.grading_policy = run_policy or RunPolicy(), grading_policy or GradingPolicy()
+        self.reference_access, self.admission_verifier = reference_access, admission_verifier
+        _require(type(include_emitted_evidence) is bool, "include_emitted_evidence must be boolean")
+        self.include_emitted_evidence = include_emitted_evidence
+        self.evaluator_binding, self.report_binding = evaluator_binding, report_binding
+        if evaluator_binding is not None or report_binding is not None:
+            from .evaluator_bindings import _binding_dependencies
+            if evaluator_binding is not None:
+                _binding_dependencies(registry, evaluator_binding)
+                _require(evaluator_binding.target in ("case", "stage")
+                         and evaluator_binding.evaluator.identity_id == evaluator_id,
+                         "lifecycle case/stage binding must match the selected evaluator")
+                if evaluator_binding.target == "stage":
+                    _require(callable(getattr(self, "evaluator_stage_evidence", None)),
+                             "stage binding requires an explicit verified stage reader")
+            if report_binding is not None:
+                _binding_dependencies(registry, report_binding)
+                _require(report_binding.target == "report"
+                         and report_binding.evaluator.identity_id in suite.evaluator_ids,
+                         "report binding must select a declared report evaluator")
+        self._validate_report_policy(self.grading_policy)
+        _driver_admission(driver, self.run_policy)
+        self.cancellation = None
+        self.descriptor = BackendDescriptor(suite.backend_id, "v1", "sphynx.lifecycle.backend.v1",
+            tuple(dict.fromkeys(("sphynx.lifecycle.run.v1", "sphynx.saved-assessment.v1",
+                                 *driver.descriptor.capabilities, *capabilities))), tuple(scopes), tuple(modes),
+            suite_ids=(suite.suite_id,), metadata={"trust_tier": "local_unverified", "driver": driver.descriptor.to_dict()})
+
+    def describe(self, suite_id):
+        _require(suite_id == self.suite.suite_id, "unknown lifecycle suite")
+        return self.suite
+
+    def _validate_report_policy(self, policy):
+        if self.report_binding is not None:
+            _require(isinstance(policy, GradingPolicy) and policy == GradingPolicy(),
+                     "report bindings currently require default grading policy; report retries/budgets are unsupported")
+
+    def _options(self, plan):
+        _require(isinstance(plan, PlanBinding) and plan.suite.definition_digest == self.suite.definition_digest,
+                 "lifecycle suite definition changed")
+        _require(plan.scope in self.descriptor.supported_scopes and plan.mode in self.descriptor.supported_modes,
+                 "unsupported lifecycle scope/mode")
+        _require(set(plan.parameters) <= {"run_policy", "grading_policy", "resume", "reuse"},
+                 "unsupported lifecycle parameters")
+        if plan.runtime:
+            validate = getattr(self.driver, "validate_runtime", None)
+            _require(callable(validate) and validate(plan.runtime) is None, "driver does not support runtime overrides")
+        run = RunPolicy.from_dict(plan.parameters["run_policy"]) if "run_policy" in plan.parameters else self.run_policy
+        grading = GradingPolicy.from_dict(plan.parameters["grading_policy"]) if "grading_policy" in plan.parameters else self.grading_policy
+        self._validate_report_policy(grading)
+        _driver_admission(self.driver, run)
+        if run.reducer_id is not None:
+            self.registry.get_policy_callable(run.reducer_id, kind="aggregation")
+        return run, grading
+
+    def _source(self):
+        seen = set()
+        for dataset in self.suite.datasets:
+            provider = self.registry.get_provider(dataset.provider_id)
+            schema = self.registry.get_schema(dataset.input_schema_id)
+            for case in provider.cases(dataset.selection):
+                _require(isinstance(case, CaseView) and case.schema_version == schema.schema_id,
+                         "provider case input schema differs")
+                _require(case.case_id not in seen, "duplicate case across lifecycle providers")
+                seen.add(case.case_id)
+                yield CaseView.validated(case.case_id, case.inputs, schema=schema, metadata=case.metadata), dataset
+
+    def cases(self, suite):
+        _require(suite.definition_digest == self.suite.definition_digest, "lifecycle suite differs")
+        return (case for case, _ in self._source())
+
+    def _execution_dependencies(self):
+        return {"datasets": [d.to_dict() for d in self.suite.datasets],
+                "input_schemas": [self.registry.get_schema(d.input_schema_id).to_dict() for d in self.suite.datasets]}
+
+    def _grading_dependencies(self, reducer_id=None):
+        evaluator = self.registry.get_evaluator(self.evaluator_id)
+        dependencies = {"evaluator": evaluator.to_dict(),
+                "assessment_schemas": [self.registry.get_schema(s).to_dict() for s in evaluator.assessment_schema_ids],
+                "reference_schemas": [self.registry.get_schema(d.reference_schema_id).to_dict()
+                                      for d in self.suite.datasets if d.reference_schema_id is not None],
+                "criteria": [self.registry.get_criterion(c).to_dict() for c in self.suite.criterion_ids],
+                "metrics": [self.registry.get_metric(c).to_dict() for c in self.suite.metric_ids],
+                "report_schema": self.registry.get_schema(self.projection_schema_id).to_dict(),
+                "projection": self.registry.get_projection(self.projection_schema_id).to_dict(),
+                "comparison": self.registry.get_policy(self.comparison_policy_id, kind="comparison").to_dict(),
+                "reducer": None if reducer_id is None else self.registry.get_policy(reducer_id, kind="aggregation").to_dict()}
+        if self.evaluator_binding is not None or self.report_binding is not None:
+            from .evaluator_bindings import _binding_dependencies
+            for name in ("evaluator_binding", "report_binding"):
+                binding = getattr(self, name)
+                if binding is not None:
+                    dependencies[name] = _binding_dependencies(self.registry, binding)
+        if self.include_emitted_evidence:
+            dependencies["emitted_evidence_policy"] = "verified-attempt-artifacts.v1"
+        return dependencies
+
+    def resolve(self, plan):
+        run, grading = self._options(plan)
+        return ResolvedBinding({"backend": self.descriptor.to_dict(), "suite": self.suite.to_dict(),
+            "candidate": _thaw(_object(self.driver.candidate_identity(plan.candidate), "candidate identity")),
+            "scope": plan.scope, "mode": plan.mode, "runtime": _thaw(plan.runtime),
+            "run_policy": run.to_dict(), "grading_policy": grading.to_dict(),
+            "execution_dependencies": self._execution_dependencies(),
+            "grading_dependencies": self._grading_dependencies(run.reducer_id),
+            "resume": _thaw(plan.parameters.get("resume")), "reuse": _thaw(plan.parameters.get("reuse"))})
+
+    def admit(self, plan, resolved):
+        _require(self.resolve(plan).resolution_digest == resolved.resolution_digest, "lifecycle resolution changed")
+        cases = tuple(self.cases(plan.suite))
+        _require(bool(cases), "lifecycle provider has no selected cases")
+        facts = {"cohort_sha256": contract_digest({"cases": [c.to_dict() for c in cases]}),
+                 "case_count": len(cases), "execution_dependencies": self._execution_dependencies()}
+        verified = {} if self.admission_verifier is None else self.admission_verifier(plan, cases)
+        verified = _thaw(_object(verified, "admission verification"))
+        facts["verification"] = verified
+        return AdmissionBinding(resolved.resolution_digest, facts, "local_unverified",
+                                verified.get("artifact_bytes_verified", False),
+                                verified.get("candidate_source_bytes_verified", False))
+
+    def recheck(self, plan, resolved, admission):
+        current = self.admit(plan, resolved)
+        _require(current.to_dict() == admission.to_dict(), "lifecycle assets/cohort/admission changed")
+
+    @staticmethod
+    def _run_ref(value):
+        if value is None:
+            return None
+        _require(isinstance(value, Mapping) and set(value) <= {"path", "definition_sha256", "head_sha256"}
+                 and {"path", "definition_sha256"} <= set(value), "invalid serialized lifecycle reference")
+        return LifecycleRunRef(Path(value["path"]), value["definition_sha256"], value.get("head_sha256"))
+
+    def execute(self, plan, resolved, admission, output_dir):
+        self.recheck(plan, resolved, admission)
+        run, grading = self._options(plan)
+        execution_identity = {key: _thaw(resolved.identity[key]) for key in
+                              ("backend", "suite", "scope", "mode", "runtime", "execution_dependencies")}
+        verification = admission.facts["verification"]
+        execution_identity["admission_fixed"] = _thaw(verification.get("fixed", {}))
+        execution_identity["admission_candidate"] = _thaw(verification.get("candidate", {}))
+        return execute_lifecycle(self.driver, plan.candidate, self.cases(plan.suite), output_dir or ".sphynx/lifecycle",
+            identity=execution_identity, policy=run, grading_policy=grading, cancellation=self.cancellation,
+            resume=self._run_ref(plan.parameters.get("resume")), reuse=self._run_ref(plan.parameters.get("reuse")),
+            recheck=lambda: self.recheck(plan, resolved, admission))
+
+    def accepts_reference(self, native_ref, kind):
+        ref = native_ref.run if isinstance(native_ref, LifecycleGradingRef) else native_ref
+        if kind == "run" and not isinstance(native_ref, LifecycleRunRef) or kind == "grading" and not isinstance(native_ref, LifecycleGradingRef):
+            return False
+        if not isinstance(ref, LifecycleRunRef):
+            return False
+        try:
+            definition, _ = _read_json(ref.path / "definition.json")
+            return definition["identity"]["backend"]["backend_id"] == self.descriptor.backend_id
+        except (LifecycleError, KeyError, TypeError):
+            return False
+
+    def _run(self, ref):
+        _require(self.accepts_reference(ref, "run"), "foreign lifecycle run")
+        record = verify_lifecycle_run(ref)
+        identity = record["definition"]["identity"]
+        _require(identity["backend"] == self.descriptor.to_dict() and identity["suite"] == self.suite.to_dict()
+                 and identity["execution_dependencies"] == self._execution_dependencies(),
+                 "lifecycle execution definitions changed")
+        return record
+
+    def reference(self, native_ref, kind):
+        if kind == "run":
+            record = self._run(native_ref)
+            return ReferenceBinding(native_ref.run_id, record["status"], "local_unverified", native_ref.run_id,
+                                    {"cleanup_status": record["cleanup_status"]})
+        record = self._grading(native_ref)
+        successes = {(r["case_id"], r["trial"]) for r in record["rows"] if r["failure"] is None}
+        planned = len(record["run"]["definition"]["cases"]) * record["run"]["definition"]["policy"]["trials"]
+        return ReferenceBinding(native_ref.grading_id, "completed" if len(successes) == planned and not record.get("report_assessment_failure") else "incomplete",
+                                "local_unverified", native_ref.run.run_id)
+
+    def _references(self, run_record):
+        expected = {case["case_id"]: case for case in run_record["definition"]["cases"]}
+        references = {}
+        for case, dataset in self._source():
+            _require(case.case_id in expected and case.to_dict() == expected[case.case_id],
+                     "provider case changed since lifecycle execution")
+            references[case.case_id] = ({} if dataset.reference_schema_id is None else
+                self.registry.get_provider(dataset.provider_id).reference_for(case.case_id, access=self.reference_access))
+        _require(set(references) == set(expected), "grading provider cohort differs")
+        return references
+
+    def assess(self, native_run):
+        return self.assess_with_policy(native_run)
+
+    def assess_with_policy(self, native_run, policy=None):
+        run = self._run(native_run)
+        if self.report_binding is not None:
+            default = run["definition"].get("default_grading_policy")
+            self._validate_report_policy(policy if policy is not None else
+                GradingPolicy.from_dict(default) if default is not None else GradingPolicy())
+        references = self._references(run)
+        reducer_id = run["definition"]["policy"]["reducer_id"]
+        identity = {"grading_dependencies": self._grading_dependencies(reducer_id),
+                    "reference_hashes": {case: contract_digest(ref) for case, ref in references.items()}}
+        evaluator = self.registry.get_evaluator_callable(self.evaluator_id)
+        emitted = {}
+        if self.include_emitted_evidence:
+            for event in run["events"]:
+                data = event["data"]
+                if event["event"] == "artifact":
+                    emitted.setdefault((data["case_id"], data["trial"], data["attempt"]), []).append(data["binding"])
+        def evaluate(case, attempt, grading):
+            evidence = []
+            bindings = dict(attempt["artifacts"])
+            if attempt.get("output_binding"):
+                bindings["outputs"] = attempt["output_binding"]
+            selected_bindings = list(bindings.items())
+            selected_bindings.extend((binding["role"], binding) for binding in
+                emitted.get((case.case_id, grading.trial, grading.attempt), ()))
+            seen = set()
+            for role, binding in selected_bindings:
+                if self.include_emitted_evidence and binding["path"] in seen:
+                    continue
+                seen.add(binding["path"])
+                evidence.append(EvidenceView(native_run.run_id + ":" + binding["path"], binding["sha256"],
+                    "application/json" if role == "outputs" else "application/octet-stream", role,
+                    self.driver.descriptor.driver_id, "local_owner", case_id=case.case_id,
+                    metadata={"trial": grading.trial, "attempt": grading.attempt}))
+            context = _verified_evaluator_context(case=case, outputs=attempt["outputs"],
+                references=references[case.case_id], evidence=tuple(evidence), run_id=grading.run_id,
+                grading_id=grading.grading_id, trust_tier="local_unverified", verified_by=self.descriptor.backend_id,
+                metadata={"trial": grading.trial, "attempt": grading.attempt, "grading_attempt": grading.grading_attempt,
+                          "candidate_failure": attempt["failure"], "reused": attempt.get("reused", False)})
+            if self.evaluator_binding is None:
+                rows = tuple(evaluator(context))
+            else:
+                from .evaluator_bindings import _dispatch_binding
+                stage = (self.evaluator_stage_evidence(native_run, self.evaluator_binding.selector(context))
+                         if self.evaluator_binding.target == "stage" else None)
+                rows = _dispatch_binding(self.registry, self.evaluator_binding, context, stage=stage)
+            allowed_evidence = {view.evidence_id for view in evidence}
+            for row in rows:
+                _require(isinstance(row, Assessment) and row.case_id == case.case_id
+                         and row.criterion_id in self.suite.criterion_ids and row.evaluator_id == self.evaluator_id
+                         and row.run_id == grading.run_id and row.grading_id == grading.grading_id
+                         and row.trial == grading.trial and row.attempt == grading.attempt
+                         and set(row.evidence_ids) <= allowed_evidence, "evaluator assessment identity or evidence differs")
+                if row.payload_schema is not None:
+                    _require(row.payload_schema["schema_id"] in self.registry.get_evaluator(self.evaluator_id).assessment_schema_ids,
+                             "evaluator emitted an undeclared assessment schema")
+                    self._assessment(row.to_dict())  # Validate against the registered, not caller-substituted schema.
+            return {"assessments": [row.to_dict() for row in rows]}
+        grading = assess_lifecycle(native_run, evaluate, identity=identity, policy=policy)
+        record = verify_lifecycle_grading(grading)
+        journal = LifecycleJournal(grading.path, grading.definition_sha256)
+        with journal.writer():
+            if reducer_id is not None:
+                value = self.registry.get_policy_callable(reducer_id, kind="aggregation")(record)
+                binding = journal.artifact("analysis", _raw(_object(value, "analysis projection")))
+                journal.append("analysis", {"policy_id": reducer_id, "binding": binding})
+                record["analysis"] = _thaw(_object(value, "analysis projection"))
+            projection = self.registry.get_projection_callable(self.projection_schema_id)(record)
+            value = projection.to_dict() if isinstance(projection, ReportProjection) else projection
+            value = self.registry.get_schema(self.projection_schema_id).validate(value)
+            binding = journal.artifact("report", _raw(value))
+            head = journal.append("projection", {"schema_id": self.projection_schema_id, "binding": binding})
+            if self.report_binding is not None:
+                from .evaluator_bindings import _dispatch_binding, _verified_report_context
+                # Report grading is one attempt per saved pass. A later regrade
+                # is distinct; do not retry quality outcomes or rerun candidates.
+                context = _verified_report_context(outputs=_thaw(value), references=_thaw(references),
+                    run_id=grading.run.run_id, grading_id=grading.grading_id,
+                    trust_tier="local_unverified", verified_by=self.descriptor.backend_id,
+                    evidence_ids=(grading.run.run_id + ":" + binding["path"],))
+                try:
+                    rows = _dispatch_binding(self.registry, self.report_binding, context)
+                    payload = {"binding_digest": self.report_binding.binding_digest,
+                               "rows": [row.to_dict() for row in rows]}
+                    report_rows = journal.artifact("report_assessments", _raw(payload))
+                    head = journal.append("report_assessments", {"binding": report_rows})
+                except Exception as exc:
+                    head = journal.append("report_assessment_failure", {
+                        "binding_digest": self.report_binding.binding_digest,
+                        "failure": "evaluator_error", "error_type": type(exc).__name__})
+        return LifecycleGradingRef(grading.path, grading.definition_sha256, grading.run, head)
+
+    def _grading(self, ref):
+        _require(self.accepts_reference(ref, "grading"), "foreign lifecycle grading pass")
+        self._run(ref.run)
+        record = verify_lifecycle_grading(ref)
+        reducer_id = record["run"]["definition"]["policy"]["reducer_id"]
+        _require(record["definition"]["identity"]["grading_dependencies"] == self._grading_dependencies(reducer_id),
+                 "grading definitions changed; retain the matching registered versions")
+        journal = LifecycleJournal(ref.path, ref.definition_sha256)
+        for event in record["events"]:
+            if event["event"] in ("analysis", "projection"):
+                value = json.loads(journal.read_artifact(event["data"]["binding"]))
+                record[event["event"]] = value
+            if event["event"] == "report_assessments":
+                value = json.loads(journal.read_artifact(event["data"]["binding"]))
+                _require(self.report_binding is not None
+                         and value.get("binding_digest") == self.report_binding.binding_digest
+                         and set(value) == {"binding_digest", "rows"} and type(value["rows"]) is list,
+                         "saved report assessment binding differs")
+                record["report_assessments"] = value["rows"]
+            if event["event"] == "report_assessment_failure":
+                _require(self.report_binding is not None and event["data"].get("binding_digest")
+                         == self.report_binding.binding_digest, "saved report failure binding differs")
+                record["report_assessment_failure"] = event["data"]["failure"]
+        return record
+
+    def report(self, native_grading):
+        record = self._grading(native_grading)
+        _require("projection" in record, "saved lifecycle report projection is missing")
+        run = record["run"]["definition"]
+        identity = run["identity"]
+        planned = len(run["cases"]) * run["policy"]["trials"]
+        observed = len({(row["case_id"], row["trial"]) for row in record["rows"] if row["failure"] is None})
+        # Do not add cases, references, commands or arbitrary driver metadata to
+        # presentation. The native projection and its serialized bytes stay exact.
+        candidate = run["candidate_identity"]
+        nested = candidate.get("identity")
+        candidate = {key: value for key, value in candidate.items() if key in
+                     ("authority", "candidate_id", "name", "version", "revision", "head_sha", "commit_sha")
+                     and type(value) is str}
+        if isinstance(nested, Mapping):
+            candidate["identity"] = {key: value for key, value in nested.items()
+                if key in ("schema_version", "identity_id", "version", "digest") and type(value) is str}
+        evaluator = self.registry.get_evaluator(self.evaluator_id)
+        context = {"suite_id": self.suite.suite_id, "suite_version": self.suite.version,
+                   "run_id": native_grading.run.run_id, "grading_id": native_grading.grading_id,
+                   "scope": identity["scope"], "mode": identity["mode"],
+                   "status": "completed" if observed == planned and not record.get("report_assessment_failure") else "incomplete",
+                   "trust_tier": "local_unverified", "candidate": candidate,
+                   "evaluator": {"id": evaluator.evaluator_id, "version": evaluator.version,
+                                 "implementation_id": evaluator.implementation_id},
+                   "execution_policy": run["policy"],
+                   "coverage": {"required_trials": planned, "observed_trials": observed,
+                                "missing_trials": planned - observed},
+                   "metric_definitions": {name: {"unit": self.registry.get_metric(name).unit,
+                                                   "direction": self.registry.get_metric(name).direction}
+                                          for name in self.suite.metric_ids}}
+        return LifecycleProjection(self.registry.get_schema(self.projection_schema_id).validate(record["projection"]), context=context)
+
+    def _assessment(self, data):
+        data = dict(data); data.pop("schema_version", None)
+        payload = data.pop("payload_schema", None)
+        if payload is None:
+            return Assessment(**data)
+        schema = self.registry.get_schema(payload["schema_id"])
+        _require(all(getattr(schema, key) == payload[key] for key in ("schema_id", "version", "implementation_id")),
+                 "saved assessment schema binding differs")
+        return Assessment.structured(schema=schema, **data)
+
+    def assessments(self, native_grading, case_id=None):
+        record = self._grading(native_grading)
+        return tuple(self._assessment(data) for row in record["rows"] if row["failure"] is None
+                     for data in row["output"].get("assessments", []) if case_id is None or data["case_id"] == case_id)
+
+    def report_assessments(self, native_grading):
+        from .evaluator_bindings import ReportAssessment, REPORT_ASSESSMENT_SCHEMA
+        record = self._grading(native_grading)
+        _require(not record.get("report_assessment_failure"), "saved report evaluator failed")
+        rows = []
+        for raw in record.get("report_assessments", []):
+            data = dict(raw)
+            _require(data.pop("schema_version", None) == REPORT_ASSESSMENT_SCHEMA
+                     and data.pop("scope", None) == "report", "invalid report assessment envelope")
+            payload = data.pop("payload_schema", None)
+            if payload is not None:
+                schema = self.registry.get_schema(payload["schema_id"])
+                _require(set(payload) == {"schema_id", "version", "implementation_id"}
+                         and all(getattr(schema, key) == payload[key] for key in payload),
+                         "saved report assessment schema differs")
+                data["schema"] = schema
+            row = ReportAssessment(**data)
+            _require(row.run_id == native_grading.run.run_id and row.grading_id == native_grading.grading_id
+                     and self.report_binding is not None
+                     and row.evaluator_id == self.report_binding.evaluator.identity_id,
+                     "saved report assessment identity differs")
+            rows.append(row)
+        return tuple(rows)
+
+    def compare(self, baseline_grading, candidate_grading):
+        baseline, candidate = self._grading(baseline_grading), self._grading(candidate_grading)
+        self._comparison_conditions(baseline, candidate)
+        return self.registry.get_policy_callable(self.comparison_policy_id, kind="comparison")(baseline, candidate)
+
+    @staticmethod
+    def _comparison_conditions(baseline, candidate):
+        left, right = baseline["run"]["definition"], candidate["run"]["definition"]
+        fixed_left = {k: v for k, v in left["identity"].items() if k != "admission_candidate"}
+        fixed_right = {k: v for k, v in right["identity"].items() if k != "admission_candidate"}
+        _comparison_require(contract_digest({"identity": fixed_left, "cases": left["cases"],
+                                  "policy": {k: v for k, v in left["policy"].items() if k != "reuse"}}) ==
+                 contract_digest({"identity": fixed_right, "cases": right["cases"],
+                                  "policy": {k: v for k, v in right["policy"].items() if k != "reuse"}}),
+                 "incompatible lifecycle execution/comparison conditions")
+        _comparison_require(baseline["definition"]["identity"] == candidate["definition"]["identity"],
+                 "incompatible grading/reference/analysis conditions")
+        _comparison_require(baseline["definition"]["policy"] == candidate["definition"]["policy"],
+                 "incompatible grading retry/budget conditions")
+
+
+    def compare_view(self, baseline_grading, candidate_grading):
+        from ._comparison_adapters import _sources, _view
+        baseline, candidate = self._grading(baseline_grading), self._grading(candidate_grading)
+        conditions = [{"execution_identity": row["run"]["definition"]["identity"],
+                       "execution_policy": row["run"]["definition"]["policy"],
+                       "grading_identity": row["definition"]["identity"],
+                       "grading_policy": row["definition"]["policy"]} for row in (baseline, candidate)]
+        sources = _sources(self, baseline_grading, candidate_grading, conditions=conditions)
+        try:
+            self._comparison_conditions(baseline, candidate)
+        except _ComparisonMismatch as exc:
+            return _view(sources, {"policy_id": self.comparison_policy_id, "refusal": str(exc)},
+                         status="incompatible", reason=str(exc))
+        projector = getattr(self, "project_comparison", None)
+        if not callable(projector):
+            return _view(sources, {}, status="unavailable",
+                         reason="No common view adapter is registered for this native comparison policy; use compare().")
+        native = self.registry.get_policy_callable(self.comparison_policy_id, kind="comparison")(baseline, candidate)
+        return projector(sources, native)