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

sphynx/pr_evaluations.py

@@ -0,0 +1,560 @@
+"""Permitted PR coordination values; private rules and source bodies stay on the service."""
+from __future__ import annotations
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from datetime import datetime
+import re
+from types import MappingProxyType
+from typing import Any, ClassVar, cast
+
+from ._analytical_values import (_Values, require, keys, identifier, identity, digest, count,
+    ReportProjectionSummary, MetricProjectionSummary, sha, frame, score_bits, text)
+from .analytical_views import ProjectionProof, _cell, _details
+from .evaluation_protocols import VersionedIdentity
+from .workflow_contracts import WorkflowContractError
+
+_PR = re.compile(r'https://github\.com/([A-Za-z0-9][A-Za-z0-9-]*)/([A-Za-z0-9][A-Za-z0-9_.-]*)/pull/([1-9][0-9]*)\Z')
+_SHA = re.compile(r'[0-9a-f]{40}\Z')
+_METHOD = re.compile(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z')
+_CODE = re.compile(r'[a-z_]{1,64}\Z')
+_STATES = {'pending','preparing','queued','running','grading','publishing','completed','incomplete','failed','unsupported'}
+
+
+def _saved(value: Any, prefix: str) -> str:
+    require(type(value) is str and re.fullmatch(prefix+r'_[0-9a-f]{32}', value) is not None,
+            'invalid PR operation identity')
+    return value
+
+
+def _commit(value: Any) -> str:
+    require(type(value) is str and _SHA.fullmatch(value) is not None, 'source revision needs a full lowercase 40-character commit SHA')
+    return value
+
+
+def _pr(value: Any) -> str:
+    require(type(value) is str and len(value)<=512, 'use a canonical HTTPS GitHub PR URL')
+    matched = _PR.fullmatch(value)
+    require(matched is not None, 'use a canonical HTTPS GitHub PR URL without a query or trailing slash')
+    assert matched is not None
+    require(int(matched[3])<=2**63-1, 'PR number exceeds its supported range')
+    return value
+
+
+def _boolean(value: Any) -> bool:
+    require(type(value) is bool, 'PR state needs an explicit boolean')
+    return value
+
+
+def _code(value: Any) -> str:
+    require(type(value) is str and _CODE.fullmatch(value) is not None, 'invalid PR state code')
+    return value
+
+
+def _exact_id(value: Any) -> VersionedIdentity:
+    require(isinstance(value, VersionedIdentity)); digest(value.digest)
+    return value
+
+
+def _time(value: Any) -> datetime:
+    require(type(value) is str and len(value)<=64, 'invalid PR timestamp')
+    try:
+        result=datetime.fromisoformat(value.replace('Z','+00:00'))
+        require(result.tzinfo is not None and result.utcoffset() is not None, 'PR timestamp needs a timezone')
+        return result
+    except ValueError:
+        raise WorkflowContractError('invalid PR timestamp') from None
+
+
+class _PrValues(_Values):
+    SCHEMA: ClassVar[str | None] = None
+    def to_dict(self) -> dict[str, Any]:
+        value=super().to_dict()
+        return value if self.SCHEMA is None else {'schema_version':self.SCHEMA, **value}
+    @classmethod
+    def _fields(cls, value: Mapping[str, Any]) -> dict[str, Any]:
+        names={item.name for item in fields(cast(Any,cls))}
+        result=keys(value, names if cls.SCHEMA is None else names|{'schema_version'})
+        if cls.SCHEMA is not None: require(result.pop('schema_version')==cls.SCHEMA, 'unsupported PR response version')
+        return result
+
+
+@dataclass(frozen=True)
+class PrEvaluationRequest(_PrValues):
+    """Constrain the server-selected private template and both exact PR revisions."""
+    template_id: str
+    candidate_pr: str
+    expected_base_sha: str
+    expected_head_sha: str
+    candidate_method: str | None = None
+    def __post_init__(self) -> None:
+        identifier(self.template_id); _pr(self.candidate_pr)
+        for name in ('expected_base_sha','expected_head_sha'):
+            value=getattr(self,name)
+            require(type(value) is str, 'source revision needs a complete hexadecimal commit SHA')
+            object.__setattr__(self,name,_commit(value.lower()))
+        require(self.candidate_method is None or type(self.candidate_method) is str and _METHOD.fullmatch(self.candidate_method) is not None,
+                'candidate_method needs a stable method identifier')
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> PrEvaluationRequest:
+        result=cls(**cls._fields(value))
+        require(result.to_dict()==dict(value), 'PR response changed its canonical request')
+        return result
+
+
+@dataclass(frozen=True)
+class PrSourceRevisions(_PrValues):
+    SCHEMA: ClassVar[str] = 'sphynx.private.pr-revisions.v1'
+    candidate_pr: str
+    base_repository: str
+    base_repository_id: int
+    head_repository: str
+    head_repository_id: int
+    base_sha: str
+    head_sha: str
+    base_tree_sha: str
+    head_tree_sha: str
+    def __post_init__(self) -> None:
+        _pr(self.candidate_pr)
+        for repository in (self.base_repository,self.head_repository):
+            require(type(repository) is str and re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9][A-Za-z0-9_.-]*',repository) is not None)
+        for number in (self.base_repository_id,self.head_repository_id): require(count(number,nullable=False,maximum=2**53-1)!=0)
+        for name in ('base_sha','head_sha','base_tree_sha','head_tree_sha'): _commit(getattr(self,name))
+    @classmethod
+    def from_dict(cls, value: Mapping[str,Any]) -> PrSourceRevisions: return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrOperationError(_PrValues):
+    stage: str
+    code: str
+    def __post_init__(self) -> None:
+        require(self.stage=='coordination'); _code(self.code)
+    @classmethod
+    def from_dict(cls, value: Mapping[str,Any]) -> PrOperationError: return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrRequirementStatus(_PrValues):
+    requirement_id: str
+    suite_id: str
+    scope: str
+    mode: str
+    bank_id: str
+    release_id: str
+    cohort: VersionedIdentity
+    state: str
+    error_code: str | None
+    def __post_init__(self) -> None:
+        for name in ('requirement_id','suite_id','bank_id','release_id'): identifier(getattr(self,name))
+        require(self.scope in ('component','subsystem','system') and self.mode in ('local','hosted'))
+        _exact_id(self.cohort); require(self.state in _STATES)
+        if self.error_code is not None: _code(self.error_code)
+    @classmethod
+    def from_dict(cls, value: Mapping[str,Any]) -> PrRequirementStatus:
+        values=cls._fields(value);values['cohort']=identity(values['cohort']);return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrEvaluationStatus(_PrValues):
+    SCHEMA: ClassVar[str] = 'sphynx.pr-evaluation.v1'
+    id: str
+    status: str
+    authority: str
+    request: PrEvaluationRequest = field(repr=False)
+    template: VersionedIdentity
+    revisions: PrSourceRevisions | None
+    plan_digest: str | None
+    expected_children: int
+    decision_id: str | None
+    error: PrOperationError | None
+    deadline_at: str
+    created_at: str
+    updated_at: str
+    requirements: tuple[PrRequirementStatus,...] = field(repr=False)
+    def __post_init__(self) -> None:
+        _saved(self.id,'preval'); require(self.authority=='current_operation_status_not_acceptance')
+        require(self.status in ('preparing','running','waiting_for_reports','waiting_for_review','evaluating','completed','failed'))
+        require(isinstance(self.request,PrEvaluationRequest)); _exact_id(self.template)
+        require(self.template.identity_id==self.request.template_id)
+        require(count(self.expected_children,nullable=False,maximum=64)!=0)
+        require(isinstance(self.requirements,(tuple,list)) and len(self.requirements)==self.expected_children)
+        require(all(isinstance(item,PrRequirementStatus) for item in self.requirements))
+        require(len({item.requirement_id for item in self.requirements})==len(self.requirements))
+        object.__setattr__(self,'requirements',tuple(self.requirements))
+        require(self.error is None or isinstance(self.error,PrOperationError))
+        if self.revisions is None: require(self.plan_digest is None)
+        else:
+            require(isinstance(self.revisions,PrSourceRevisions));digest(self.plan_digest)
+            require((self.revisions.candidate_pr,self.revisions.base_sha,self.revisions.head_sha)==
+                    (self.request.candidate_pr,self.request.expected_base_sha,self.request.expected_head_sha))
+            require(self.revisions.base_repository.lower()==self.request.candidate_pr.removeprefix('https://github.com/').split('/pull/')[0].lower())
+        if self.decision_id is not None: _saved(self.decision_id,'prdec');require(self.status=='completed')
+        if self.status=='completed': require(self.decision_id is not None and self.revisions is not None)
+        require(_time(self.deadline_at)>_time(self.created_at) and _time(self.updated_at)>=_time(self.created_at))
+    @classmethod
+    def from_dict(cls, value: Mapping[str,Any]) -> PrEvaluationStatus:
+        values=cls._fields(value);values['request']=PrEvaluationRequest.from_dict(values['request']);values['template']=identity(values['template'])
+        if values['revisions'] is not None:values['revisions']=PrSourceRevisions.from_dict(values['revisions'])
+        if values['error'] is not None:values['error']=PrOperationError.from_dict(values['error'])
+        require(type(values['requirements']) is list and len(values['requirements'])<=64)
+        values['requirements']=tuple(PrRequirementStatus.from_dict(item) for item in values['requirements']);return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrDecisionReceipt(_PrValues):
+    """Historical decision evidence; current eligibility is a separate field."""
+    SCHEMA: ClassVar[str] = 'sphynx.pr-decision-receipt.v1'
+    decision_id: str
+    plan_id: str
+    policy: VersionedIdentity
+    inputs_digest: str
+    outcome: str
+    passed: bool | None
+    reason_code: str
+    authority: str
+    def __post_init__(self) -> None:
+        _saved(self.decision_id,'prdec');_saved(self.plan_id,'preval');_exact_id(self.policy);digest(self.inputs_digest)
+        require(self.passed is None or type(self.passed) is bool)
+        allowed={'passed':(True,{'policy_passed'}),'failed':(False,{'policy_failed'}),
+                 'undetermined':(None,{'policy_undetermined','policy_not_supported','policy_evaluation_failed','required_report_incomplete'})}
+        require(self.outcome in allowed and self.passed is allowed[self.outcome][0] and self.reason_code in allowed[self.outcome][1])
+        require(self.authority=='historical_decision_requires_current_service_check')
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrDecisionReceipt:
+        values=cls._fields(value);values['policy']=identity(values['policy']);return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrReportView(_PrValues):
+    report: ReportProjectionSummary
+    metrics: tuple[MetricProjectionSummary,...]
+    projection: ProjectionProof
+    team_id: str = field(repr=False)
+    def __post_init__(self) -> None:
+        require(isinstance(self.report,ReportProjectionSummary) and isinstance(self.projection,ProjectionProof));identifier(self.team_id)
+        require(isinstance(self.metrics,(tuple,list)) and 1<=len(self.metrics)<=128 and all(isinstance(m,MetricProjectionSummary) for m in self.metrics))
+        require(len({m.metric_id for m in self.metrics})==len(self.metrics))
+        require(all((m.run_id,m.grading_id)==(self.report.run_id,self.report.grading_id) for m in self.metrics))
+        require(self.projection.row_count in (1+len(self.metrics),2+len(self.metrics)))
+        require(self.projection.plan_digest==sha(frame('sphynx.evaluation.plan.v2',self.team_id,self.projection.event_id,self.projection.source_digest,self.projection.manifest_digest,self.projection.row_count)))
+        object.__setattr__(self,'metrics',tuple(self.metrics))
+    def to_dict(self)->dict[str,Any]:
+        return {'report':self.report.to_dict(),'metrics':[m.to_dict() for m in self.metrics],
+                'projection':{'team_id':self.team_id,**self.projection.to_dict()}}
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrReportView:
+        values=keys(value,{'report','metrics','projection'});proof=keys(values['projection'],{'team_id','event_id','source_digest','plan_digest','manifest_digest','row_count','commit_hash'})
+        team=proof.pop('team_id');require(type(values['metrics']) is list and len(values['metrics'])<=128)
+        return cls(ReportProjectionSummary.from_dict(values['report']),tuple(MetricProjectionSummary.from_dict(m) for m in values['metrics']),ProjectionProof.from_dict(proof),team)
+
+
+@dataclass(frozen=True)
+class PrCaseChangeCounts(_PrValues):
+    improved: int
+    regressed: int
+    unchanged: int
+    unavailable: int
+    total: int
+    def __post_init__(self)->None:
+        for value in (self.improved,self.regressed,self.unchanged,self.unavailable,self.total):count(value,nullable=False)
+        require(self.improved+self.regressed+self.unchanged+self.unavailable==self.total)
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrCaseChangeCounts:return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrMetricChange(_PrValues):
+    delta_bits: str | None
+    paired: int | None
+    unavailable: int | None
+    total: int | None
+    case_changes: PrCaseChangeCounts | None
+    def __post_init__(self)->None:
+        if self.delta_bits is not None:score_bits(self.delta_bits)
+        for value in (self.paired,self.unavailable,self.total):count(value)
+        require((self.paired is None)==(self.unavailable is None)==(self.total is None))
+        if self.total is not None:
+            require(self.paired is not None and self.unavailable is not None)
+            assert self.paired is not None and self.unavailable is not None
+            require(self.paired+self.unavailable==self.total)
+        require(self.case_changes is None or isinstance(self.case_changes,PrCaseChangeCounts))
+    @property
+    def delta(self)->float|None:return score_bits(self.delta_bits) if self.delta_bits is not None else None
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrMetricChange:
+        values=cls._fields(value)
+        if values['case_changes'] is not None:values['case_changes']=PrCaseChangeCounts.from_dict(values['case_changes'])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrRegressionSummary(_PrValues):
+    SCHEMA: ClassVar[str] = 'sphynx.pr-regressions.v1'
+    baseline_grading_id: str
+    candidate_grading_id: str
+    method_id: str
+    metrics: Mapping[str,PrMetricChange] = field(repr=False)
+    case_change_count: int
+    comparison_digest: str
+    evidence_link: str
+    def __post_init__(self)->None:
+        text(self.baseline_grading_id);text(self.candidate_grading_id);identifier(self.method_id);digest(self.comparison_digest)
+        count(self.case_change_count,nullable=False)
+        require(isinstance(self.metrics,Mapping) and 0<len(self.metrics)<=128)
+        for name,value in self.metrics.items():text(name);require(isinstance(value,PrMetricChange))
+        require(sum(value.case_changes.total for value in self.metrics.values() if value.case_changes is not None)==self.case_change_count)
+        require(type(self.evidence_link) is str and re.fullmatch(r'/v1/pr-evaluations/preval_[0-9a-f]{32}/requirements/[A-Za-z0-9._~%:-]+/case-changes',self.evidence_link) is not None)
+        object.__setattr__(self,'metrics',MappingProxyType(dict(self.metrics)))
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrRegressionSummary:
+        values=cls._fields(value);require(isinstance(values['metrics'],Mapping))
+        values['metrics']={name:PrMetricChange.from_dict(item) for name,item in values['metrics'].items()};return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrComparisonStatus(_PrValues):
+    status: str
+    reason_code: str
+    regressions: PrRegressionSummary | None
+    uncertainty: None
+    def __post_init__(self)->None:
+        require(self.uncertainty is None)
+        if self.status=='not_requested':
+            require(self.reason_code=='comparison_not_part_of_frozen_profile' and self.regressions is None)
+        elif self.status=='unavailable':
+            require(self.reason_code=='comparison_report_unavailable' and self.regressions is None)
+        else:
+            require((self.status,self.reason_code) in (('supported','native_comparison'),('incomplete','native_comparison_incomplete'))
+                and isinstance(self.regressions,PrRegressionSummary))
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrComparisonStatus:
+        values=cls._fields(value)
+        if values['regressions'] is not None:values['regressions']=PrRegressionSummary.from_dict(values['regressions'])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class PrRequirementResult(_PrValues):
+    status: PrRequirementStatus
+    baseline: VersionedIdentity
+    conditions: Mapping[str,VersionedIdentity] = field(repr=False)
+    review_status: str
+    provisional: bool
+    acceptance_eligible: bool
+    report_availability: str
+    report: PrReportView | None
+    evidence_link: str | None
+    board_link: str | None
+    comparison: PrComparisonStatus
+    def __post_init__(self)->None:
+        require(isinstance(self.status,PrRequirementStatus));_exact_id(self.baseline)
+        require(isinstance(self.conditions,Mapping) and {'protocol','bank','evaluator','runtime'}<=set(self.conditions)
+                and set(self.conditions)<={'protocol','bank','evaluator','runtime','labels','references','hardware'})
+        for condition in self.conditions.values():_exact_id(condition)
+        object.__setattr__(self,'conditions',MappingProxyType(dict(self.conditions)))
+        require(self.review_status in ('pending','provisional','reviewed','disputed','needs_changes'))
+        _boolean(self.provisional);_boolean(self.acceptance_eligible);require(self.provisional==(self.review_status!='reviewed'))
+        require(self.report_availability in ('available','unavailable') and isinstance(self.comparison,PrComparisonStatus))
+        require((self.report is not None)==(self.report_availability=='available'))
+        if self.report is not None:
+            require(isinstance(self.report,PrReportView))
+            require(self.report.projection.row_count==1+len(self.report.metrics)+int(self.comparison.regressions is not None))
+            require((self.report.report.scope,self.report.report.mode)==(self.status.scope,self.status.mode))
+            require({k:v for k,v in self.report.report.bindings.items() if k!='candidate'}==dict(self.conditions))
+            if self.status.state=='completed':
+                coverage=self.report.report.coverage
+                require(self.report.report.status=='completed' and coverage.required is not None and coverage.required>0
+                        and coverage.required==coverage.observed and coverage.missing==0 and coverage.undefined==0)
+    def to_dict(self)->dict[str,Any]:
+        value=super().to_dict();value.pop('status');return {**self.status.to_dict(),**value}
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrRequirementResult:
+        core={item.name for item in fields(PrRequirementStatus)}
+        extra={item.name for item in fields(cls)}-{'status'};values=keys(value,core|extra)
+        status=PrRequirementStatus.from_dict({key:values.pop(key) for key in core})
+        values['baseline']=identity(values['baseline']);require(isinstance(values['conditions'],Mapping))
+        values['conditions']={key:identity(item) for key,item in values['conditions'].items()}
+        if values['report'] is not None:values['report']=PrReportView.from_dict(values['report'])
+        values['comparison']=PrComparisonStatus.from_dict(values['comparison']);return cls(status=status,**values)
+
+
+@dataclass(frozen=True)
+class PrResultApplicability(_PrValues):
+    basis: str
+    latest_pr_revision_checked: bool
+    policy_current: bool
+    bank_acceptance_eligible: bool
+    reports_available: bool
+    def __post_init__(self)->None:
+        require(self.basis in ('requested_base_head','frozen_base_head') and self.latest_pr_revision_checked is False)
+        for value in (self.policy_current,self.bank_acceptance_eligible,self.reports_available):_boolean(value)
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrResultApplicability:return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrRequiredCoverage(_PrValues):
+    unit: str
+    required: int
+    completed: int
+    incomplete: int
+    failed: int
+    pending: int
+    verified_reports: int
+    def __post_init__(self)->None:
+        require(self.unit=='required_evaluation' and count(self.required,nullable=False,maximum=64)!=0)
+        for name in ('completed','incomplete','failed','pending','verified_reports'):count(getattr(self,name),nullable=False,maximum=self.required)
+        require(self.completed+self.incomplete+self.failed+self.pending==self.required)
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrRequiredCoverage:return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrEvaluationResult(_PrValues):
+    """Current permitted read of a frozen operation and its historical decision."""
+    SCHEMA: ClassVar[str] = 'sphynx.pr-evaluation-result.v1'
+    authority: str
+    operation: PrEvaluationStatus
+    decision: PrDecisionReceipt | None
+    current_acceptance: bool | None
+    applicability: PrResultApplicability
+    coverage: PrRequiredCoverage
+    requirements: tuple[PrRequirementResult,...] = field(repr=False)
+    checked_at: str | None = None
+    def __post_init__(self)->None:
+        require(self.authority=='current_authorized_frozen_revision_summary' and isinstance(self.operation,PrEvaluationStatus))
+        require(self.operation.status in ('running','waiting_for_reports','waiting_for_review','evaluating','completed','failed'))
+        if self.checked_at is not None:_time(self.checked_at)
+        require(isinstance(self.applicability,PrResultApplicability) and isinstance(self.coverage,PrRequiredCoverage))
+        require(self.applicability.basis==('requested_base_head' if self.operation.revisions is None else 'frozen_base_head'))
+        require(isinstance(self.requirements,(tuple,list)) and len(self.requirements)==self.operation.expected_children
+                and all(isinstance(r,PrRequirementResult) for r in self.requirements))
+        object.__setattr__(self,'requirements',tuple(self.requirements)); statuses={r.requirement_id:r for r in self.operation.requirements}
+        require(len({r.status.requirement_id for r in self.requirements})==len(self.requirements)
+                and all(statuses.get(r.status.requirement_id)==r.status for r in self.requirements))
+        require((self.decision is not None)==(self.operation.decision_id is not None))
+        if self.decision is not None:
+            require(isinstance(self.decision,PrDecisionReceipt) and (self.decision.plan_id,self.decision.decision_id)==(self.operation.id,self.operation.decision_id))
+        require(self.current_acceptance is None or type(self.current_acceptance) is bool)
+        completed=sum(r.status.state=='completed' for r in self.requirements);incomplete=sum(r.status.state=='incomplete' for r in self.requirements)
+        failed=sum(r.status.state in ('failed','unsupported') for r in self.requirements);available=sum(r.report is not None for r in self.requirements)
+        require((self.coverage.required,self.coverage.completed,self.coverage.incomplete,self.coverage.failed,self.coverage.pending,self.coverage.verified_reports)==
+                (len(self.requirements),completed,incomplete,failed,len(self.requirements)-completed-incomplete-failed,available))
+        if self.operation.status not in ('completed','failed'):
+            require(self.decision is None and self.current_acceptance is None and completed+incomplete==len(self.requirements))
+        require(self.applicability.bank_acceptance_eligible==all(r.acceptance_eligible for r in self.requirements)
+                and self.applicability.reports_available==(available==len(self.requirements)))
+        expected=self.decision.passed if self.decision is not None and self.applicability.policy_current and self.applicability.bank_acceptance_eligible and completed==available==len(self.requirements) else None
+        require(self.current_acceptance is expected, 'PR acceptance differs from explicit current eligibility')
+        from urllib.parse import quote
+        for r in self.requirements:
+            if r.evidence_link is not None:require(r.evidence_link==f'/v1/pr-evaluations/{self.operation.id}/requirements/{quote(r.status.requirement_id,safe="")}/projection')
+            if r.comparison.regressions is not None:
+                require(r.comparison.regressions.evidence_link==f'/v1/pr-evaluations/{self.operation.id}/requirements/{quote(r.status.requirement_id,safe="")}/case-changes')
+                if r.report is not None:require(r.comparison.regressions.candidate_grading_id==r.report.report.grading_id)
+            if r.report is not None:require(r.evidence_link is not None)
+            if r.board_link is not None:require(type(r.board_link) is str and re.fullmatch('/v1/banks/'+re.escape(quote(r.status.bank_id,safe=''))+r'/boards/[A-Za-z0-9._~%:-]+',r.board_link) is not None)
+    @classmethod
+    def from_dict(cls,value:Mapping[str,Any])->PrEvaluationResult:
+        require(isinstance(value,Mapping));values=cls._fields({'checked_at':None,**value});values['operation']=PrEvaluationStatus.from_dict(values['operation'])
+        if values['decision'] is not None:values['decision']=PrDecisionReceipt.from_dict(values['decision'])
+        values['applicability']=PrResultApplicability.from_dict(values['applicability']);values['coverage']=PrRequiredCoverage.from_dict(values['coverage'])
+        require(type(values['requirements']) is list and len(values['requirements'])<=64)
+        values['requirements']=tuple(PrRequirementResult.from_dict(item) for item in values['requirements']);return cls(**values)
+    def to_dict(self)->dict[str,Any]:
+        value=super().to_dict()
+        if self.checked_at is None:del value['checked_at']
+        return value
+    def summary(self)->str:
+        label={True:'pass',False:'fail',None:'undetermined'}
+        historical='unavailable' if self.decision is None else label[self.decision.passed]
+        return (f'PR evaluation {self.operation.id}: {self.operation.status}. Acceptance at this read: {label[self.current_acceptance]}. '
+                f'Saved decision: {historical} (historical). Verified reports: {self.coverage.verified_reports}/{self.coverage.required}.')
+    def to_text(self)->str:return self.summary()
+    def to_markdown(self,*,include_details:bool=False)->str:
+        require(type(include_details) is bool)
+        lines=[self.summary(),'','| Requirement | Scope | Location | Work | Report | Review |','| --- | --- | --- | --- | --- | --- |']
+        for r in self.requirements:
+            lines.append('| '+' | '.join(_cell(value) for value in (r.status.requirement_id,r.status.scope,r.status.mode,r.status.state,r.report_availability,r.review_status))+' |')
+        for r in self.requirements:
+            comparison=r.comparison.regressions
+            if comparison is not None:
+                lines.extend(['',f'{_cell(r.status.requirement_id)}: comparison {r.comparison.status}; {comparison.case_change_count} case/metric rows.'])
+                lines.extend(['','| Metric | Candidate minus baseline | Paired | Unavailable |','| --- | --- | --- | --- |'])
+                # Full fields and all metrics remain in the details view.
+                for name,value in list(comparison.metrics.items())[:6]:
+                    values=(name,'unknown' if value.delta is None else f'{value.delta:+.6g}',
+                        'unknown' if value.paired is None else value.paired,'unknown' if value.unavailable is None else value.unavailable)
+                    lines.append('| '+' | '.join(_cell(v) for v in values)+' |')
+                if len(comparison.metrics)>6:lines.append(f'Showing 6 of {len(comparison.metrics)} metrics. All metrics are available in comparison.regressions.metrics and the details view.')
+                lines.append('Descriptive native comparison. Uncertainty is not validated. Full values and case pages remain available.')
+        result='\n'.join(lines)
+        return result+_details(self.to_dict()) if include_details else result
+
+
+@dataclass(frozen=True)
+class PrCaseChange(_PrValues):
+    """One native case/metric delta. No question or reference text is present."""
+    case_id: str
+    metric_id: str
+    direction: str
+    baseline_bits: str | None
+    candidate_bits: str | None
+    delta_bits: str | None
+    status: str
+    def __post_init__(self) -> None:
+        text(self.case_id); text(self.metric_id)
+        require(self.direction in ('higher','lower'))
+        values=[None if v is None else score_bits(v) for v in (self.baseline_bits,self.candidate_bits,self.delta_bits)]
+        a,b,delta=values
+        if a is None or b is None:
+            require(delta is None and self.status=='unavailable')
+        else:
+            require(delta is not None and delta==b-a)
+            assert delta is not None
+            expected='unchanged' if delta==0 else 'improved' if (delta>0)==(self.direction=='higher') else 'regressed'
+            require(self.status==expected)
+    @property
+    def baseline(self) -> float | None:return None if self.baseline_bits is None else score_bits(self.baseline_bits)
+    @property
+    def candidate(self) -> float | None:return None if self.candidate_bits is None else score_bits(self.candidate_bits)
+    @property
+    def delta(self) -> float | None:return None if self.delta_bits is None else score_bits(self.delta_bits)
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> PrCaseChange:return cls(**cls._fields(value))
+
+
+@dataclass(frozen=True)
+class PrCaseChangePage(_PrValues):
+    """A bounded page bound to the operation's committed comparison."""
+    SCHEMA: ClassVar[str]='sphynx.pr-case-changes.v1'
+    authority: str
+    plan_id: str
+    requirement_id: str
+    source_digest: str
+    comparison_digest: str
+    offset: int
+    total: int
+    items: tuple[PrCaseChange,...]
+    next_cursor: str | None
+    def __post_init__(self) -> None:
+        require(self.authority=='current_authorized_committed_comparison')
+        _saved(self.plan_id,'preval');identifier(self.requirement_id)
+        digest(self.source_digest);digest(self.comparison_digest)
+        count(self.offset,nullable=False);count(self.total,nullable=False)
+        object.__setattr__(self,'items',tuple(self.items))
+        require(len(self.items)<=500 and all(isinstance(v,PrCaseChange) for v in self.items))
+        require(self.offset+len(self.items)<=self.total and (bool(self.items) or self.offset==self.total))
+        require(len({(v.case_id,v.metric_id) for v in self.items})==len(self.items))
+        require((self.next_cursor is None)==(self.offset+len(self.items)==self.total))
+        if self.next_cursor is not None:_case_cursor(self.next_cursor)
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> PrCaseChangePage:
+        values=cls._fields(value);require(type(values['items']) is list)
+        values['items']=tuple(PrCaseChange.from_dict(v) for v in values['items'])
+        return cls(**values)
+
+
+def _case_cursor(value: Any) -> str:
+    require(type(value) is str and 1<=len(value)<=2048 and re.fullmatch(r'[A-Za-z0-9_-]+',value) is not None,'invalid comparison page cursor')
+    return value

sphynx/progress.py

@@ -0,0 +1,89 @@
+"""Read-only presentation of cached work status, without polling or retrying."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Literal, cast
+
+from .diagnostics import Diagnostic, _safe_text
+
+ProgressState = Literal['queued', 'running', 'waiting_for_review', 'partial',
+                        'failed', 'completed', 'cancelling', 'cancelled', 'unknown']
+_STATES = {name: name for name in ('queued', 'running', 'waiting_for_review', 'partial',
+                                  'failed', 'completed', 'cancelling', 'cancelled')}
+_STATES.update({'preparing': 'running', 'building': 'running', 'grading': 'running',
+                'waiting_for_reports': 'running', 'evaluating': 'running',
+                'incomplete': 'partial', 'canceled': 'cancelled'})
+_TERMINAL = {'failed', 'completed', 'cancelled'}
+
+
+@dataclass(frozen=True)
+class ProgressView:
+    """An observation, not an execution control or an acceptance verdict.
+
+    ``state`` groups explicit native names for display. ``native_status`` keeps
+    the original name. Unknown names stay unknown. Counts, percentages and time
+    estimates are absent because these handles do not supply them.
+    """
+
+    operation: Literal['submission', 'execution', 'grading']
+    native_status: str
+    state: ProgressState
+    terminal: bool | None
+    identities: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.operation not in ('submission', 'execution', 'grading'):
+            raise ValueError('unknown progress operation')
+        if not isinstance(self.native_status, str) or not self.native_status:
+            raise ValueError('progress needs the native status')
+        if self.state not in {*_STATES.values(), 'unknown'}:
+            raise ValueError('unknown presentation state')
+        if self.terminal is not None and type(self.terminal) is not bool:
+            raise ValueError('terminal must be boolean or unknown')
+        safe = Diagnostic('progress', 'Cached work status', (), recovery=self.identities)
+        object.__setattr__(self, 'identities', MappingProxyType(dict(safe.recovery)))
+
+    def to_dict(self) -> dict:
+        return {'schema_version': 'sphynx.progress.v1', 'operation': self.operation,
+                'native_status': self.native_status, 'state': self.state,
+                'terminal': self.terminal, 'identities': dict(self.identities)}
+
+    def to_text(self) -> str:
+        status = _safe_text(self.native_status)
+        lines = [f'{self.operation}: {self.state} (native: {status})']
+        lines.extend(f'{key}: {_safe_text(value)}' for key, value in self.identities.items())
+        if self.state == 'unknown':
+            lines.append('This native state has no registered display meaning.')
+        if self.state == 'completed':
+            lines.append('Work completed. Quality and acceptance require their own report checks.')
+        lines.append('This is cached status. Refresh the same handle for a newer observation.')
+        return '\n'.join(lines)
+
+    def __str__(self) -> str:
+        return self.to_text()
+
+
+def _progress(operation, status, identities, *, terminal=None, complete=None, failed=None):
+    # Missing or unrecognized native values never become queued or completed.
+    native = status if isinstance(status, str) and status else 'unavailable'
+    state = _STATES.get(native, 'unknown')
+    if operation == 'execution' and native == 'captured':
+        state = 'completed'
+    if terminal is False and state in _TERMINAL:
+        state = 'unknown'
+    if (state == 'completed' and complete is False) or (state == 'failed' and failed is False):
+        state = 'unknown'
+    if terminal is None and state != 'unknown':
+        terminal = state in _TERMINAL if state != 'partial' else None
+    return ProgressView(operation, native, cast(ProgressState, state), terminal,
+                        {key: value for key, value in identities.items() if value is not None})
+
+
+def _hosted_progress(record, operation):
+    key = {'submission': 'experiment_id', 'execution': 'run_id', 'grading': 'evaluation_id'}[operation]
+    identities = {key: record['id']}
+    identities.update({key: record[key] for key in ('experiment_id', 'run_id', 'evaluation_id')
+                       if record.get(key) is not None})
+    return _progress(operation, record.get('status'), identities)