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

sphynx/workflows.py

@@ -0,0 +1,792 @@
+"""Domain-neutral Suite -> Plan -> Run -> Report orchestration.
+
+Registered backends own candidate protocols, datasets, admission, native records,
+evaluators, report shapes and comparison policy. This module does not load domain
+assets, interpret metric layouts, authenticate evidence, or create a sandbox.
+"""
+from __future__ import annotations
+
+import math
+import time
+import uuid
+
+from collections.abc import Iterable, Mapping
+from dataclasses import InitVar, dataclass, field
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+from .assessment_contracts import Assessment, CaseView
+from .assessment_selection import AssessmentSelector
+from .evaluator_bindings import ReportAssessment
+from .workflow_contracts import (
+    AdmissionBinding, DatasetDefinition, PlanBinding, ReferenceBinding,
+    ReportProjection, ResolvedBinding, SuiteDefinition, WorkflowBackend,
+    WorkflowContractError, _text, _thaw, contract_digest,
+)
+from .workflow_defaults import default_workflow_registry
+from .workflow_decisions import Verdict
+from .workflow_registry import WorkflowRegistry
+from .workflow_async import (
+    AsyncWorkflowBackend, GradingSnapshot, SubmissionError, SubmissionIntent,
+    SubmissionSnapshot,
+)
+from .stage_contracts import StageEvidence, StageEvidenceBackend, StageSelector
+
+
+if TYPE_CHECKING:
+    from .comparison_views import ComparisonView
+    from .diagnostics import Diagnostic
+    from .progress import ProgressView
+
+
+# Keep the public error import while registry errors remain catchable through it.
+WorkflowError = WorkflowContractError
+_ADMISSION_TOKEN = object()
+
+
+class WorkflowTimeoutError(TimeoutError):
+    """Waiting ended; the handle still identifies the original remote work."""
+
+    def __init__(self, message: str, handle: Any) -> None:
+        self.handle = handle
+        super().__init__(message)
+
+    @property
+    def diagnostic(self) -> Diagnostic:
+        from .diagnostics import explain_error
+        return explain_error(self)
+
+
+class PendingWorkError(WorkflowError):
+    """Asynchronous work failed; its native identity remains on handle."""
+
+    def __init__(self, message: str, handle: Any) -> None:
+        self.handle = handle
+        super().__init__(message)
+
+
+class GradingRequestError(WorkflowError):
+    """An uncertain grading POST retains its run and recovery key."""
+
+    def __init__(self, message: str, *, run_id: str, idempotency_key: str) -> None:
+        self.run_id, self.idempotency_key = run_id, idempotency_key
+        super().__init__(message)
+
+
+def _async_backend(backend: WorkflowBackend, capability: str) -> AsyncWorkflowBackend:
+    if capability not in backend.descriptor.capabilities or not isinstance(backend, AsyncWorkflowBackend):
+        raise WorkflowError("backend does not support " + capability)
+    return backend
+
+
+def _wait(handle: Any, ready: Any, *, timeout: float, poll_interval: float,
+          on_progress: Any = None) -> Any:
+    for value, name in ((timeout, "timeout"), (poll_interval, "poll_interval")):
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0:
+            raise WorkflowError(name + " must be finite and positive")
+    if on_progress is not None and not callable(on_progress):
+        raise WorkflowError("on_progress must be callable")
+    deadline = time.monotonic() + timeout
+    current = handle
+    while True:
+        if on_progress is not None:
+            on_progress(current.snapshot)
+        if current.snapshot.failed:
+            raise PendingWorkError(current.snapshot.reason or "asynchronous work failed", current)
+        result = ready(current)
+        if result is not None:
+            return result
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise WorkflowTimeoutError("wait timed out; retain the handle and resume polling", current)
+        time.sleep(min(poll_interval, remaining))
+        current = current.refresh()
+
+
+def _stages(backend: WorkflowBackend, native_ref: Any, selector: StageSelector) -> tuple[StageEvidence, ...]:
+    if not isinstance(selector, StageSelector):
+        raise WorkflowError("stage evidence requires an exact StageSelector")
+    if "sphynx.stage-evidence.v1" not in backend.descriptor.capabilities or not isinstance(backend, StageEvidenceBackend):
+        raise WorkflowError("backend does not support stage evidence")
+    rows = backend.stage_evidence(native_ref, selector)
+    if not isinstance(rows, tuple) or any(not isinstance(row, StageEvidence) for row in rows):
+        raise WorkflowError("stage evidence backend must return a tuple of StageEvidence")
+    if any(row.selector != selector for row in rows):
+        raise WorkflowError("backend returned stage evidence outside the exact selection")
+    # The backend authorizes this projection and retains its native visibility
+    # label. A common selector never grants access or invents a global ACL.
+    return rows
+
+
+def _registry(value: WorkflowRegistry | None) -> WorkflowRegistry:
+    if value is None:
+        return default_workflow_registry()
+    if not isinstance(value, WorkflowRegistry):
+        raise WorkflowError("registry must be WorkflowRegistry")
+    return value
+
+
+def _reference_backend(native_ref: Any, kind: str, registry: WorkflowRegistry | None,
+                       backend_id: str | None) -> tuple[WorkflowRegistry, str, WorkflowBackend]:
+    selected = _registry(registry)
+    if backend_id is not None:
+        backend = selected.get_backend(backend_id)
+        if not backend.accepts_reference(native_ref, kind):
+            raise WorkflowError(f"backend does not recognize the native {kind} reference")
+        return selected, backend_id, backend
+    matches = []
+    for descriptor in selected.list_backends():
+        backend = selected.get_backend(descriptor.backend_id)
+        if backend.accepts_reference(native_ref, kind):
+            matches.append((descriptor.backend_id, backend))
+    if len(matches) != 1:
+        raise WorkflowError(
+            f"native {kind} reference has no unique registered backend; select backend_id explicitly"
+        )
+    identifier, backend = matches[0]
+    return selected, identifier, backend
+
+
+def _reference(backend: WorkflowBackend, native_ref: Any, kind: str) -> ReferenceBinding:
+    binding = backend.reference(native_ref, kind)
+    if not isinstance(binding, ReferenceBinding):
+        raise WorkflowError("backend reference reader must return ReferenceBinding")
+    if binding.record_id is None:
+        reason = binding.metadata.get("reason")
+        raise WorkflowError(reason if isinstance(reason, str) and reason else "no readable native record identity")
+    return binding
+
+
+def _case_views(rows: Iterable[CaseView]) -> Iterable[CaseView]:
+    for row in rows:
+        if not isinstance(row, CaseView):
+            raise WorkflowError("backend case access must produce CaseView values")
+        yield row
+
+
+def _assessment_views(rows: Iterable[Assessment], case_id: str | None = None) -> Iterable[Assessment]:
+    for row in rows:
+        if not isinstance(row, Assessment):
+            raise WorkflowError("backend assessment access must produce Assessment values")
+        if case_id is not None and row.case_id != case_id:
+            raise WorkflowError("backend returned assessments outside the selected case")
+        yield row
+
+
+@dataclass(frozen=True)
+class Suite:
+    """Reusable registered cases, criteria, and execution requirements.
+
+    A native pack can be selected through ``from_pack`` when its adapter is
+    registered. ``from_registry`` selects custom extensions through the same
+    flow. Registration metadata does not establish execution admission.
+    """
+
+    suite_id: str
+    registry: WorkflowRegistry | None = field(default=None, repr=False, compare=False)
+    _definition: SuiteDefinition = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        registry = _registry(self.registry)
+        definition, _ = registry.resolve_suite(self.suite_id)
+        object.__setattr__(self, "registry", registry)
+        object.__setattr__(self, "_definition", definition)
+
+    @classmethod
+    def from_pack(cls, pack_id: str, *, registry: WorkflowRegistry | None = None) -> Suite:
+        """Select a registered native adapter through its existing pack ID."""
+        return cls(pack_id, registry=registry)
+
+    @classmethod
+    def from_registry(cls, suite_id: str, *, registry: WorkflowRegistry) -> Suite:
+        """Select a suite from explicit operator-provided extension bindings."""
+        return cls(suite_id, registry=registry)
+
+    def _registered(self, *, scope: str | None = None,
+                    mode: str | None = None) -> tuple[SuiteDefinition, WorkflowBackend]:
+        assert self.registry is not None
+        return self.registry.verify_suite(self._definition, scope=scope, mode=mode)
+
+    @property
+    def definition(self) -> SuiteDefinition:
+        return self._registered()[0]
+
+    @property
+    def backend_id(self) -> str:
+        return self.definition.backend_id
+
+    @property
+    def criterion_ids(self) -> tuple[str, ...]:
+        return self.definition.criterion_ids
+
+    @property
+    def metric_ids(self) -> tuple[str, ...]:
+        return self.definition.metric_ids
+
+    @property
+    def evaluator_ids(self) -> tuple[str, ...]:
+        return self.definition.evaluator_ids
+
+    @property
+    def datasets(self) -> tuple[DatasetDefinition, ...]:
+        return self.definition.datasets
+
+    def cases(self) -> Iterable[CaseView]:
+        """Read candidate-permitted cases; preserve a backend's lazy iteration."""
+        definition, backend = self._registered()
+        rows = backend.cases(definition)
+        if isinstance(rows, tuple):
+            if any(not isinstance(row, CaseView) for row in rows):
+                raise WorkflowError("backend case access must produce CaseView values")
+            return rows
+        try:
+            iter(rows)
+        except TypeError:
+            raise WorkflowError("backend case access must return an iterable") from None
+        return _case_views(rows)
+
+    def plan(self, candidate: Any, *, scope: str = "component", mode: str = "local",
+             parameters: Mapping[str, Any] | None = None,
+             runtime: Mapping[str, Any] | None = None) -> Plan:
+        """Select a candidate and supported conditions; the backend validates them."""
+        return Plan(self, candidate, scope=scope, mode=mode,
+                    parameters={} if parameters is None else parameters,
+                    runtime={} if runtime is None else runtime)
+
+
+@dataclass(frozen=True)
+class Plan:
+    """Selected suite, opaque candidate, conditions, and backend parameters."""
+
+    suite: Suite
+    candidate: Any = field(repr=False, compare=False)
+    scope: str = "component"
+    mode: str = "local"
+    parameters: Mapping[str, Any] = field(default_factory=dict)
+    runtime: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.suite, Suite):
+            raise WorkflowError("plan requires a Suite")
+        definition, _ = self.suite._registered(scope=self.scope, mode=self.mode)
+        selected = PlanBinding(definition, self.candidate, self.scope, self.mode,
+                               self.parameters, self.runtime)
+        object.__setattr__(self, "parameters", selected.parameters)
+        object.__setattr__(self, "runtime", selected.runtime)
+
+    def _selected(self) -> tuple[PlanBinding, WorkflowBackend]:
+        definition, backend = self.suite._registered(scope=self.scope, mode=self.mode)
+        return PlanBinding(definition, self.candidate, self.scope, self.mode,
+                           self.parameters, self.runtime), backend
+
+    def resolve(self) -> ResolvedPlan:
+        """Bind backend metadata without asset reads or candidate execution."""
+        selected, backend = self._selected()
+        return ResolvedPlan(self, backend.resolve(selected))
+
+    def run(self, output_dir: str | Path | None = None) -> Run:
+        """Resolve, admit, and execute. Saved assessment remains separate."""
+        from .execution_capabilities import validate_execution_requirement
+        _, backend = self._selected()
+        validate_execution_requirement(backend.descriptor, scope=self.scope, mode=self.mode,
+                                       operation="execute")
+        return self.resolve().admit().execute(output_dir)
+
+    def submission_intent(self, *, idempotency_key: str | None = None) -> SubmissionIntent:
+        """Retain the recovery identity before a hosted submission attempt."""
+        _, backend = self._selected()
+        _async_backend(backend, "sphynx.async-submission.v1")
+        return SubmissionIntent(uuid.uuid4().hex if idempotency_key is None else idempotency_key,
+                                self.resolve().binding.identity)
+
+    def submit(self, *, intent: SubmissionIntent | None = None,
+               idempotency_key: str | None = None) -> Submission:
+        """Submit once. Retain intent to recover an uncertain POST response."""
+        if intent is not None and idempotency_key is not None:
+            raise WorkflowError("provide intent or idempotency_key, not both")
+        from .execution_capabilities import validate_execution_requirement
+        _, backend = self._selected()
+        validate_execution_requirement(backend.descriptor, scope=self.scope, mode=self.mode,
+                                       operation="submit")
+        resolved = self.resolve()
+        selected, backend = resolved._verified()
+        asynchronous = _async_backend(backend, "sphynx.async-submission.v1")
+        intent = intent if intent is not None else SubmissionIntent(
+            uuid.uuid4().hex if idempotency_key is None else idempotency_key, resolved.binding.identity)
+        if not isinstance(intent, SubmissionIntent) or contract_digest(intent.request_identity) != contract_digest(resolved.binding.identity):
+            raise WorkflowError("submission intent does not match the resolved plan")
+        admission = resolved.admit()
+        backend.recheck(selected, resolved.binding, admission.binding)
+        try:
+            native = asynchronous.submit(selected, resolved.binding, admission.binding, intent.idempotency_key)
+            handle = Submission(native, registry=self.suite.registry, backend_id=self.suite.backend_id)
+            if (handle.snapshot.idempotency_key != intent.idempotency_key or
+                    contract_digest(handle.snapshot.request_identity) != contract_digest(intent.request_identity)):
+                raise WorkflowError("submission response differs from its retained intent")
+            return handle
+        except SubmissionError:
+            raise
+        except Exception as exc:
+            raise SubmissionError(str(exc), intent=intent) from exc
+
+
+@dataclass(frozen=True)
+class ResolvedPlan:
+    """Backend resolution metadata, separate from execution admission."""
+
+    plan: Plan
+    binding: ResolvedBinding
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.plan, Plan) or not isinstance(self.binding, ResolvedBinding):
+            raise WorkflowError("resolved plan requires a Plan and ResolvedBinding")
+        self._verified()
+
+    def _verified(self) -> tuple[PlanBinding, WorkflowBackend]:
+        selected, backend = self.plan._selected()
+        current = backend.resolve(selected)
+        if not isinstance(current, ResolvedBinding):
+            raise WorkflowError("backend resolution must return ResolvedBinding")
+        if "evaluation_protocol" in selected.suite.metadata:
+            from .evaluation_protocols import EvaluationProtocol
+            protocol = EvaluationProtocol.from_dict(selected.suite.metadata["evaluation_protocol"])
+            if current.identity.get("evaluation_protocol_digest") != protocol.protocol_digest:
+                raise WorkflowError("backend resolution must bind the evaluation protocol digest")
+        if current.resolution_digest != self.binding.resolution_digest:
+            raise WorkflowError("resolved settings or candidate identity changed; resolve the plan again")
+        return selected, backend
+
+    @property
+    def native_invocation(self) -> Any:
+        """Compatibility access to the backend's opaque native resolution."""
+        return self.binding.native_ref
+
+    @property
+    def status(self) -> str:
+        return self.binding.status
+
+    @property
+    def artifact_bytes_verified(self) -> bool:
+        return self.binding.artifact_bytes_verified
+
+    @property
+    def plan_digest(self) -> str:
+        return contract_digest(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        definition, backend = self.plan.suite._registered(scope=self.plan.scope, mode=self.plan.mode)
+        return {"schema_version": "sphynx.plan-view.v2", "status": self.status,
+                "suite": definition.to_dict(), "backend": backend.descriptor.to_dict(),
+                "scope": self.plan.scope, "mode": self.plan.mode,
+                "parameters": _thaw(self.plan.parameters), "runtime": _thaw(self.plan.runtime),
+                "resolution": self.binding.to_dict(), "artifact_bytes_verified": False}
+
+    def admit(self) -> Admission:
+        """Apply backend-owned identity, asset, access and capability checks."""
+        selected, backend = self._verified()
+        admitted = backend.admit(selected, self.binding)
+        return Admission(self, admitted, _token=_ADMISSION_TOKEN)
+
+
+@dataclass(frozen=True)
+class Admission:
+    """Backend admission facts, rechecked before candidate execution."""
+
+    resolved: ResolvedPlan
+    binding: AdmissionBinding
+    _token: InitVar[object] = None
+
+    def __post_init__(self, _token: object) -> None:
+        if _token is not _ADMISSION_TOKEN:
+            raise WorkflowError("create admission through resolved_plan.admit()")
+        if not isinstance(self.resolved, ResolvedPlan) or not isinstance(self.binding, AdmissionBinding):
+            raise WorkflowError("admission requires a ResolvedPlan and AdmissionBinding")
+        if self.binding.resolution_digest != self.resolved.binding.resolution_digest:
+            raise WorkflowError("admission does not match the resolved plan")
+
+    def __getattr__(self, name: str) -> Any:
+        # Native convenience names remain available without baking their fields
+        # into the common schema. The fact's meaning stays backend-owned.
+        binding = object.__getattribute__(self, "binding")
+        if name in binding.facts:
+            return binding.facts[name]
+        raise AttributeError(name)
+
+    @property
+    def facts(self) -> Mapping[str, Any]:
+        return self.binding.facts
+
+    @property
+    def status(self) -> str:
+        return self.binding.status
+
+    @property
+    def trust_tier(self) -> str:
+        return self.binding.trust_tier
+
+    @property
+    def artifact_bytes_verified(self) -> bool:
+        return self.binding.artifact_bytes_verified
+
+    @property
+    def candidate_source_bytes_verified(self) -> bool:
+        return self.binding.candidate_source_bytes_verified
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema_version": "sphynx.admission-view.v2",
+                "plan_digest": self.resolved.plan_digest, **self.binding.to_dict()}
+
+    def execute(self, output_dir: str | Path | None = None) -> Run:
+        selected, backend = self.resolved._verified()
+        from .execution_capabilities import validate_execution_requirement
+        validate_execution_requirement(backend.descriptor, scope=selected.scope, mode=selected.mode,
+                                       operation="execute")
+        backend.recheck(selected, self.resolved.binding, self.binding)
+        native = backend.execute(selected, self.resolved.binding, self.binding, output_dir)
+        return Run(native, registry=self.resolved.plan.suite.registry,
+                   backend_id=self.resolved.plan.suite.backend_id)
+
+
+@dataclass(frozen=True)
+class Run:
+    """Opaque native execution evidence bound to its registered backend."""
+
+    native_ref: Any = field(repr=False)
+    registry: WorkflowRegistry | None = field(default=None, repr=False, compare=False)
+    backend_id: str | None = None
+
+    def __post_init__(self) -> None:
+        registry, identifier, _ = _reference_backend(self.native_ref, "run", self.registry, self.backend_id)
+        object.__setattr__(self, "registry", registry)
+        object.__setattr__(self, "backend_id", identifier)
+
+    def _backend(self) -> WorkflowBackend:
+        assert self.registry is not None and self.backend_id is not None
+        backend = self.registry.get_backend(self.backend_id)
+        if not backend.accepts_reference(self.native_ref, "run"):
+            raise WorkflowError("backend no longer recognizes the native run reference")
+        return backend
+
+    @property
+    def run_id(self) -> str:
+        binding = _reference(self._backend(), self.native_ref, "run")
+        assert binding.record_id is not None
+        return binding.run_id if binding.run_id is not None else binding.record_id
+
+    @property
+    def status(self) -> str:
+        return _reference(self._backend(), self.native_ref, "run").status
+
+    @property
+    def trust_tier(self) -> str:
+        return _reference(self._backend(), self.native_ref, "run").trust_tier
+
+    def assess(self) -> Report:
+        """Assess saved evidence without executing the candidate again."""
+        native = self._backend().assess(self.native_ref)
+        return Report(native, registry=self.registry, backend_id=self.backend_id)
+
+    def start_grading(self, *, idempotency_key: str | None = None) -> GradingPass:
+        """Request a new grading pass over saved evidence without execution."""
+        backend = _async_backend(self._backend(), "sphynx.async-grading.v1")
+        key = uuid.uuid4().hex if idempotency_key is None else idempotency_key
+        _text(key, "idempotency_key")
+        run_id = self.run_id
+        try:
+            native = backend.start_grading(self.native_ref, key)
+            result = GradingPass(native, registry=self.registry, backend_id=self.backend_id)
+            if result.snapshot.idempotency_key != key or result.snapshot.run_id != run_id:
+                raise WorkflowError("new grading pass differs from the requested run or recovery key")
+            return result
+        except Exception as exc:
+            raise GradingRequestError(str(exc), run_id=run_id, idempotency_key=key) from exc
+
+    def stage_evidence(self, selector: StageSelector) -> tuple[StageEvidence, ...]:
+        """Read verified permitted evidence for exactly one stage instance."""
+        return _stages(self._backend(), self.native_ref, selector)
+
+
+@dataclass(frozen=True)
+class Report:
+    """Backend-verified permitted presentation and selected assessments.
+
+    The backend owns its report layout and visibility rules. ``metrics`` and
+    ``counts`` are optional mapping-shaped summary conveniences. Other layouts
+    remain unchanged through the full projection. No verdict is inferred.
+    """
+
+    native_ref: Any = field(repr=False)
+    registry: WorkflowRegistry | None = field(default=None, repr=False, compare=False)
+    backend_id: str | None = None
+
+    def __post_init__(self) -> None:
+        registry, identifier, backend = _reference_backend(self.native_ref, "grading", self.registry, self.backend_id)
+        _reference(backend, self.native_ref, "grading")
+        object.__setattr__(self, "registry", registry)
+        object.__setattr__(self, "backend_id", identifier)
+
+    def _backend(self) -> WorkflowBackend:
+        assert self.registry is not None and self.backend_id is not None
+        backend = self.registry.get_backend(self.backend_id)
+        if not backend.accepts_reference(self.native_ref, "grading"):
+            raise WorkflowError("backend no longer recognizes the native grading reference")
+        return backend
+
+    def _projection(self) -> ReportProjection:
+        projection = self._backend().report(self.native_ref)
+        if not isinstance(projection, ReportProjection):
+            raise WorkflowError("backend report must implement ReportProjection")
+        return projection
+
+    @property
+    def grading_id(self) -> str:
+        binding = _reference(self._backend(), self.native_ref, "grading")
+        assert binding.record_id is not None
+        return binding.record_id
+
+    @property
+    def run_id(self) -> str | None:
+        return _reference(self._backend(), self.native_ref, "grading").run_id
+
+    @property
+    def status(self) -> str:
+        return _reference(self._backend(), self.native_ref, "grading").status
+
+    @property
+    def trust_tier(self) -> str:
+        return _reference(self._backend(), self.native_ref, "grading").trust_tier
+
+    @property
+    def metrics(self) -> Mapping[str, Any]:
+        return self._summary_mapping("metrics")
+
+    @property
+    def counts(self) -> Mapping[str, Any]:
+        return self._summary_mapping("counts")
+
+    def _summary_mapping(self, key: str) -> Mapping[str, Any]:
+        data = self.to_dict()
+        if key not in data:
+            return {}
+        value = data[key]
+        if not isinstance(value, Mapping):
+            raise WorkflowError(
+                f"backend {key} summary is not a mapping; inspect the complete report"
+            )
+        return value
+
+    def to_dict(self) -> dict[str, Any]:
+        data = self._projection().to_dict()
+        if not isinstance(data, dict):
+            raise WorkflowError("backend report projection must return a dictionary")
+        return data
+
+    def to_json(self) -> str:
+        value = self._projection().to_json()
+        if not isinstance(value, str):
+            raise WorkflowError("backend report JSON projection must return text")
+        return value
+
+    def to_markdown(self) -> str:
+        value = self._projection().to_markdown()
+        if not isinstance(value, str):
+            raise WorkflowError("backend report Markdown projection must return text")
+        return value
+
+    def decide(self, policy_id: str, *, baseline: Report | None = None,
+               parameters: Mapping[str, Any] | None = None) -> Verdict:
+        """Apply an explicit registered policy to permitted saved report data."""
+        from .workflow_decisions import decide_report
+
+        return decide_report(self, policy_id, baseline=baseline, parameters=parameters)
+
+    def report_assessments(self) -> tuple[ReportAssessment, ...]:
+        """Read saved report-scoped assessments; never execute a candidate."""
+        backend = self._backend()
+        reader = getattr(backend, "report_assessments", None)
+        if not callable(reader):
+            raise WorkflowError("backend does not support report-scoped assessment reads")
+        expected = _reference(backend, self.native_ref, "grading")
+        rows = tuple(reader(self.native_ref))
+        if any(not isinstance(row, ReportAssessment) or row.run_id != expected.run_id
+               or row.grading_id != expected.record_id for row in rows):
+            raise WorkflowError("backend returned invalid report-scoped assessment identity")
+        return rows
+
+    def assessments(self, case_id: str | None = None) -> Iterable[Assessment]:
+        """Read typed assessments while retaining a backend's lazy access."""
+        if case_id is not None:
+            _text(case_id, "case_id")
+        values = self._backend().assessments(self.native_ref, case_id)
+        if isinstance(values, tuple):
+            if any(not isinstance(value, Assessment) for value in values):
+                raise WorkflowError("backend assessment access must produce Assessment values")
+            if case_id is not None and any(value.case_id != case_id for value in values):
+                raise WorkflowError("backend returned assessments outside the selected case")
+            return values
+        try:
+            iter(values)
+        except TypeError:
+            raise WorkflowError("backend assessment access must return an iterable") from None
+        return _assessment_views(values, case_id)
+
+    def select_assessments(self, selector: AssessmentSelector) -> Iterable[Assessment]:
+        """Filter permitted assessments lazily, retaining exact case/trial identity."""
+        if not isinstance(selector, AssessmentSelector):
+            raise WorkflowError("selector must be AssessmentSelector")
+        return selector.select(self.assessments(case_id=selector.case_id))
+
+    def compare(self, baseline: Report) -> Any:
+        """Apply the shared backend's comparison policy to baseline then candidate."""
+        if not isinstance(baseline, Report):
+            raise WorkflowError("baseline must be Report")
+        candidate_backend, baseline_backend = self._backend(), baseline._backend()
+        if candidate_backend.descriptor.descriptor_digest != baseline_backend.descriptor.descriptor_digest:
+            raise WorkflowError("reports use different backend bindings")
+        return candidate_backend.compare(baseline.native_ref, self.native_ref)
+
+    def compare_view(self, baseline: Report) -> ComparisonView:
+        """Read an optional typed native comparison; never run or regrade work."""
+        from .comparison_views import ComparisonView
+        if not isinstance(baseline, Report):
+            raise WorkflowError("baseline must be Report")
+        backend, other = self._backend(), baseline._backend()
+        if backend.descriptor.descriptor_digest != other.descriptor.descriptor_digest:
+            raise WorkflowError("reports use different backend bindings")
+        reader = getattr(backend, "compare_view", None)
+        if not callable(reader):
+            raise WorkflowError("backend has no comparison view adapter; use compare() for its native result")
+        left = _reference(other, baseline.native_ref, "grading")
+        right = _reference(backend, self.native_ref, "grading")
+        view = reader(baseline.native_ref, self.native_ref)
+        if not isinstance(view, ComparisonView):
+            raise WorkflowError("backend comparison view must be ComparisonView")
+        if contract_digest(view.backend) != backend.descriptor.descriptor_digest:
+            raise WorkflowError("comparison view uses a different backend binding")
+        for source, expected in ((view.baseline, left), (view.candidate, right)):
+            if any(source.get(key) != getattr(expected, native_key) for key, native_key in
+                   (("grading_id", "record_id"), ("run_id", "run_id"), ("trust_tier", "trust_tier"), ("status", "status"))):
+                raise WorkflowError("comparison view refers to a different report identity/status")
+        return view
+
+    def stage_evidence(self, selector: StageSelector) -> tuple[StageEvidence, ...]:
+        """Select stage evidence through this report's verified native binding."""
+        return _stages(self._backend(), self.native_ref, selector)
+
+
+@dataclass(frozen=True)
+class Submission:
+    """An immutable view of submitted coordination work. Refresh returns a view."""
+
+    native_ref: Any = field(repr=False)
+    registry: WorkflowRegistry = field(repr=False, compare=False)
+    backend_id: str
+    snapshot: SubmissionSnapshot = field(init=False)
+
+    def __post_init__(self) -> None:
+        backend = _async_backend(self.registry.get_backend(self.backend_id), "sphynx.async-submission.v1")
+        snapshot = backend.submission_snapshot(self.native_ref)
+        if not isinstance(snapshot, SubmissionSnapshot):
+            raise WorkflowError("backend must provide SubmissionSnapshot")
+        object.__setattr__(self, "snapshot", snapshot)
+
+    @property
+    def submission_id(self) -> str:
+        return self.snapshot.submission_id
+
+    @property
+    def progress(self) -> ProgressView:
+        return self.snapshot.progress
+
+    @property
+    def status(self) -> str:
+        return self.snapshot.status
+
+    @property
+    def intent(self) -> SubmissionIntent:
+        return SubmissionIntent(self.snapshot.idempotency_key, self.snapshot.request_identity)
+
+    def refresh(self) -> Submission:
+        backend = _async_backend(self.registry.get_backend(self.backend_id), "sphynx.async-submission.v1")
+        updated = Submission(backend.refresh_submission(self.native_ref), self.registry, self.backend_id)
+        old, new = self.snapshot, updated.snapshot
+        if (old.submission_id != new.submission_id or old.idempotency_key != new.idempotency_key or
+                contract_digest(old.request_identity) != contract_digest(new.request_identity) or
+                any(getattr(old, name) is not None and getattr(old, name) != getattr(new, name)
+                    for name in ("run_id", "grading_id")) or
+                (old.complete and not new.complete) or (old.failed and not new.failed)):
+            raise WorkflowError("submission identity or terminal state changed during polling")
+        return updated
+
+    def wait_for_run(self, *, timeout: float = 900, poll_interval: float = 2,
+                     on_progress: Any = None) -> Run:
+        def ready(handle):
+            if handle.snapshot.native_run is None:
+                return None
+            run = Run(handle.snapshot.native_run, registry=self.registry, backend_id=self.backend_id)
+            if run.run_id != handle.snapshot.run_id:
+                raise WorkflowError("submission links a different native run")
+            return run
+        return _wait(self, ready, timeout=timeout, poll_interval=poll_interval, on_progress=on_progress)
+
+    def wait_for_report(self, *, timeout: float = 900, poll_interval: float = 2,
+                        on_progress: Any = None) -> Report:
+        def ready(handle):
+            if handle.snapshot.native_grading is None:
+                return None
+            report = Report(handle.snapshot.native_grading, registry=self.registry, backend_id=self.backend_id)
+            if report.grading_id != handle.snapshot.grading_id or report.run_id != handle.snapshot.run_id:
+                raise WorkflowError("submission links a different native grading pass")
+            return report
+        return _wait(self, ready, timeout=timeout, poll_interval=poll_interval, on_progress=on_progress)
+
+
+@dataclass(frozen=True)
+class GradingPass:
+    """A pending saved-evidence grading pass, separate from its final report."""
+
+    native_ref: Any = field(repr=False)
+    registry: WorkflowRegistry = field(repr=False, compare=False)
+    backend_id: str
+    snapshot: GradingSnapshot = field(init=False)
+
+    def __post_init__(self) -> None:
+        backend = _async_backend(self.registry.get_backend(self.backend_id), "sphynx.async-grading.v1")
+        snapshot = backend.grading_snapshot(self.native_ref)
+        if not isinstance(snapshot, GradingSnapshot):
+            raise WorkflowError("backend must provide GradingSnapshot")
+        object.__setattr__(self, "snapshot", snapshot)
+
+    @property
+    def grading_id(self) -> str:
+        return self.snapshot.grading_id
+
+    @property
+    def progress(self) -> ProgressView:
+        return self.snapshot.progress
+
+    @property
+    def status(self) -> str:
+        return self.snapshot.status
+
+    def refresh(self) -> GradingPass:
+        backend = _async_backend(self.registry.get_backend(self.backend_id), "sphynx.async-grading.v1")
+        updated = GradingPass(backend.refresh_grading(self.native_ref), self.registry, self.backend_id)
+        old, new = self.snapshot, updated.snapshot
+        if (old.grading_id != new.grading_id or old.run_id != new.run_id or
+                old.idempotency_key != new.idempotency_key or
+                contract_digest(old.request_identity) != contract_digest(new.request_identity) or
+                (old.complete and not new.complete) or (old.failed and not new.failed)):
+            raise WorkflowError("grading identity or terminal state changed during polling")
+        return updated
+
+    def wait_for_report(self, *, timeout: float = 900, poll_interval: float = 2,
+                        on_progress: Any = None) -> Report:
+        def ready(handle):
+            if handle.snapshot.completed_ref is None:
+                return None
+            report = Report(handle.snapshot.completed_ref, registry=self.registry, backend_id=self.backend_id)
+            if report.grading_id != handle.grading_id or report.run_id != handle.snapshot.run_id:
+                raise WorkflowError("completed grading links a different report")
+            return report
+        return _wait(self, ready, timeout=timeout, poll_interval=poll_interval, on_progress=on_progress)