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

sphynx/_analytical_values.py

@@ -0,0 +1,252 @@
+"""Permitted analytical value schemas; no service, policy or credential code."""
+from __future__ import annotations
+from collections.abc import Mapping
+from dataclasses import dataclass,field,fields
+import hashlib
+import json
+import math
+import re
+import struct
+from types import MappingProxyType
+from typing import Any,Callable,cast
+from .evaluation_protocols import VersionedIdentity
+from .workflow_contracts import WorkflowContractError
+
+
+def require(ok: object,message: str='invalid analytical response') -> None:
+    if not ok:raise WorkflowContractError(message)
+
+
+def identifier(value: Any,*,empty: bool=False) -> str:
+    require(type(value) is str and ((empty and value=='') or
+        re.fullmatch(r'[A-Za-z0-9._:-]{1,128}',value) is not None and value not in ('.','..')),
+        'invalid private analytical identifier')
+    return value
+
+
+def text(value: Any) -> str:
+    require(type(value) is str and bool(value.strip()) and '\0' not in value)
+    try:require(len(value.encode('utf-8'))<=1024)
+    except UnicodeError:raise WorkflowContractError('invalid analytical UTF-8 text') from None
+    return value
+
+
+def digest(value: Any) -> str:
+    require(type(value) is str and re.fullmatch(r'sha256:[0-9a-f]{64}',value) is not None)
+    return value
+
+
+def count(value: Any,*,nullable: bool=True,maximum: int=2**63-1) -> int|None:
+    require(value is None and nullable or type(value) is int and 0<=value<=maximum)
+    return value
+
+
+def keys(value: Any,names: set[str]) -> dict[str,Any]:
+    require(isinstance(value,Mapping) and set(value)==names,'invalid analytical response fields')
+    return dict(value)
+
+
+def identity(value: Any) -> VersionedIdentity:
+    values=keys(value,{'schema_version','identity_id','version','digest'})
+    text(values['identity_id']);text(values['version'])
+    return VersionedIdentity.from_dict(values)
+
+
+def score_bits(value: Any) -> float:
+    require(type(value) is str and re.fullmatch('[0-9a-f]{16}',value) is not None)
+    number=struct.unpack('>d',bytes.fromhex(value))[0]
+    require(math.isfinite(number),'analytical score must have exact finite bits')
+    return number
+
+
+def sha(value: str) -> str:
+    return 'sha256:'+hashlib.sha256(value.encode('utf-8')).hexdigest()
+
+
+def frame(profile: str,*values: object) -> str:
+    return profile+'\n'+'\n'.join(str(value) for value in values)
+
+
+def parse_json(raw: Any,*,maximum: int=65536) -> Any:
+    require(type(raw) is str)
+    try:
+        require(len(raw.encode('utf-8'))<=maximum)
+        def unique(pairs):
+            result={}
+            for key,value in pairs:require(key not in result);result[key]=value
+            return result
+        return json.loads(raw,object_pairs_hook=unique,
+            parse_constant=lambda _:(_ for _ in ()).throw(ValueError()))
+    except (ValueError,TypeError,UnicodeError,RecursionError):
+        raise WorkflowContractError('invalid analytical JSON') from None
+
+
+def wire(value: Any) -> Any:
+    if isinstance(value,(VersionedIdentity,_Values)):return value.to_dict()
+    if isinstance(value,Mapping):return {key:wire(item) for key,item in value.items()}
+    if isinstance(value,(tuple,list)):return [wire(item) for item in value]
+    return value
+
+
+class _Values:
+    def to_dict(self) -> dict[str,Any]:
+        return {item.name:wire(getattr(self,item.name)) for item in fields(cast(Any,self))}
+
+
+@dataclass(frozen=True)
+class ProjectionCoverage(_Values):
+    """Native counts and unit, including explicit unknown values."""
+    unit: str
+    required: int|None
+    observed: int|None
+    missing: int|None
+    undefined: int|None
+    def __post_init__(self) -> None:
+        text(self.unit)
+        for name in ('required','observed','missing','undefined'):count(getattr(self,name))
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> ProjectionCoverage:
+        return cls(**keys(value,{'unit','required','observed','missing','undefined'}))
+
+
+@dataclass(frozen=True)
+class ReportProjectionSummary(_Values):
+    run_id: str
+    grading_id: str
+    scope: str
+    mode: str
+    status: str
+    trust_tier: str
+    bindings: Mapping[str,VersionedIdentity]=field(repr=False)
+    coverage: ProjectionCoverage
+    def __post_init__(self) -> None:
+        for value in (self.run_id,self.grading_id,self.status,self.trust_tier):text(value)
+        require(self.scope in ('component','subsystem','system') and self.mode in ('local','hosted'))
+        require(isinstance(self.coverage,ProjectionCoverage))
+        require(isinstance(self.bindings,Mapping) and {'candidate','protocol','bank','evaluator','runtime'}<=set(self.bindings)
+            and set(self.bindings)<={'candidate','protocol','bank','evaluator','runtime','labels','references','hardware'})
+        require(all(isinstance(value,VersionedIdentity) for value in self.bindings.values()))
+        object.__setattr__(self,'bindings',MappingProxyType(dict(self.bindings)))
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> ReportProjectionSummary:
+        values=keys(value,{'run_id','grading_id','scope','mode','status','trust_tier','bindings','coverage'})
+        require(isinstance(values['bindings'],Mapping))
+        values['bindings']={key:identity(item) for key,item in values['bindings'].items()}
+        values['coverage']=ProjectionCoverage.from_dict(values['coverage'])
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class MetricProjectionSummary(_Values):
+    run_id: str
+    grading_id: str
+    metric_id: str
+    unit: str
+    direction: str
+    availability: str
+    value_kind: str
+    value_bits: str|None=field(repr=False)
+    assertion: bool|None
+    label: str|None=field(repr=False)
+    coverage: ProjectionCoverage
+    population_id: str
+    method_id: str
+    uncertainty_id: str|None
+    def __post_init__(self) -> None:
+        for name in ('run_id','grading_id','metric_id','unit','direction','population_id','method_id'):text(getattr(self,name))
+        if self.uncertainty_id is not None:text(self.uncertainty_id)
+        require(isinstance(self.coverage,ProjectionCoverage))
+        require(self.availability in ('available','missing','undefined','unavailable')
+                and self.value_kind in ('score','assertion','label','custom'))
+        available=self.availability=='available'
+        if available and self.value_kind=='score':score_bits(self.value_bits)
+        else:require(self.value_bits is None)
+        require(type(self.assertion) is bool if available and self.value_kind=='assertion' else self.assertion is None)
+        if available and self.value_kind=='label':text(self.label)
+        else:require(self.label is None)
+    @property
+    def value(self) -> float|bool|str|None:
+        """A custom value stays in its native artifact; availability is explicit."""
+        if self.availability!='available':return None
+        if self.value_kind=='score':return score_bits(self.value_bits)
+        return self.assertion if self.value_kind=='assertion' else self.label
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> MetricProjectionSummary:
+        values=keys(value,{'run_id','grading_id','metric_id','unit','direction','availability','value_kind',
+            'value_bits','assertion','label','coverage','population_id','method_id','uncertainty_id'})
+        values['coverage']=ProjectionCoverage.from_dict(values['coverage']);return cls(**values)
+
+
+@dataclass(frozen=True)
+class ComparisonProjectionSummary(_Values):
+    baseline_grading_id: str
+    candidate_grading_id: str
+    status: str
+    reason: str|None
+    policy_id: str
+    population_id: str
+    metric_ids: tuple[str,...]
+    artifact_digest: str
+    def __post_init__(self) -> None:
+        for name in ('baseline_grading_id','candidate_grading_id','policy_id','population_id'):text(getattr(self,name))
+        require(self.status in ('supported','incomplete','incompatible','unavailable'))
+        if self.reason is not None:text(self.reason)
+        require(self.status=='supported' or self.reason is not None)
+        require(isinstance(self.metric_ids,(tuple,list)) and len(self.metric_ids)<=128)
+        for name in self.metric_ids:text(name)
+        object.__setattr__(self,'metric_ids',tuple(self.metric_ids));digest(self.artifact_digest)
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> ComparisonProjectionSummary:
+        return cls(**keys(value,{'baseline_grading_id','candidate_grading_id','status','reason','policy_id',
+                                'population_id','metric_ids','artifact_digest'}))
+
+
+@dataclass(frozen=True)
+class EligibilityView(_Values):
+    """A recorded status. This object cannot grant current service permission."""
+    eligible: bool
+    reasons: tuple[str,...]
+    def __post_init__(self) -> None:
+        require(type(self.eligible) is bool and isinstance(self.reasons,(tuple,list)))
+        for reason in self.reasons:text(reason)
+        require(self.eligible or bool(self.reasons));object.__setattr__(self,'reasons',tuple(self.reasons))
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> EligibilityView:
+        return cls(**keys(value,{'eligible','reasons'}))
+
+
+@dataclass(frozen=True)
+class AuditProjectionSummary(_Values):
+    """Historical review status, with no protected target or judgment content."""
+    review_status: str
+    state: str
+    policy_id: VersionedIdentity
+    eligibility: Mapping[str,EligibilityView]=field(repr=False)
+    counts: Mapping[str,int]
+    def __post_init__(self) -> None:
+        require(self.review_status in ('pending','provisional','reviewed','disputed','needs_changes')
+                and self.state in ('active','held','withdrawn') and isinstance(self.policy_id,VersionedIdentity))
+        require(isinstance(self.eligibility,Mapping) and set(self.eligibility)=={'development','ranking','acceptance'})
+        require(all(isinstance(value,EligibilityView) and (self.state=='active' or not value.eligible)
+                    for value in self.eligibility.values()))
+        require(isinstance(self.counts,Mapping) and len(self.counts)<=32)
+        for name,value in self.counts.items():identifier(name);count(value,nullable=False)
+        object.__setattr__(self,'counts',MappingProxyType(dict(self.counts)))
+        object.__setattr__(self,'eligibility',MappingProxyType(dict(self.eligibility)))
+    @classmethod
+    def from_dict(cls,value: Mapping[str,Any]) -> AuditProjectionSummary:
+        values=keys(value,{'review_status','state','policy_id','eligibility','counts'})
+        values['policy_id']=identity(values['policy_id']);require(isinstance(values['eligibility'],Mapping))
+        values['eligibility']={key:EligibilityView.from_dict(item) for key,item in values['eligibility'].items()}
+        return cls(**values)
+
+
+ProjectionSummary=ReportProjectionSummary|MetricProjectionSummary|ComparisonProjectionSummary|AuditProjectionSummary
+
+
+def summary(kind: str,value: Mapping[str,Any]) -> ProjectionSummary:
+    readers: dict[str,Callable[[Mapping[str,Any]],ProjectionSummary]]={
+        'report':ReportProjectionSummary.from_dict,'metric':MetricProjectionSummary.from_dict,
+        'comparison':ComparisonProjectionSummary.from_dict,'audit':AuditProjectionSummary.from_dict}
+    require(type(kind) is str and kind in readers)
+    return readers[kind](value)

sphynx/_audit_client.py

@@ -0,0 +1,173 @@
+"""Lazy audit transport helpers over the existing authenticated Client."""
+from __future__ import annotations
+from collections.abc import Mapping
+import json
+from dataclasses import replace
+from typing import Any, Literal, TYPE_CHECKING
+from urllib.parse import quote, urlencode
+
+from .audit_access import ReviewHistoryPage, ReviewOperationReceipt, ReviewTargetPage, TargetReviewPage
+from .audit_contracts import BankRelease, ReviewContribution
+from .audit_requests import (BankReleaseDeclaration, BankReleaseTransition, ReviewAdjudication,
+                             _bounded, _identifier, _key, _positive_version)
+from .client import HostedClientError
+from .workflow_contracts import WorkflowContractError
+
+if TYPE_CHECKING:
+    from .diagnostics import Diagnostic
+
+AuditRequest = BankReleaseDeclaration | ReviewContribution | ReviewAdjudication | BankReleaseTransition
+
+
+class AuditRequestError(HostedClientError):
+    """Preserve the exact original write for explicit uncertain-outcome recovery."""
+    request: AuditRequest
+
+    def __init__(self, cause: HostedClientError, *, bank_id: str, release_id: str,
+                 operation: str, request: AuditRequest):
+        self.bank_id, self.release_id, self.operation = bank_id, release_id, operation
+        self.request, self.idempotency_key = request, request.idempotency_key
+        super().__init__(cause.code, 'audit request did not return a verified receipt; retain the original request and key')
+
+    @property
+    def diagnostic(self) -> Diagnostic:
+        view = super().diagnostic
+        if self.code in {'hosted_transport_failed', 'invalid_server_response', 'store_unavailable',
+                         'service_unavailable', 'hosted_request_failed'}:
+            return replace(view, summary='The audit write outcome needs to be reconciled.',
+                           next_actions=('Read current status or explicitly replay the original request and key before a new judgment/version.',),
+                           retryability='reconcile_before_retry')
+        return view
+
+
+def _invalid():
+    return HostedClientError('invalid_server_response', 'the selected-bank audit response could not be verified')
+
+
+def _path(bank, release=None):
+    path = '/v1/banks/' + quote(_identifier(bank), safe='') + '/releases'
+    if release is not None:
+        path += '/' + quote(_identifier(release), safe='')
+    return path
+
+
+def _query(*, after, through_version, limit, maximum, target_cursor=False):
+    if type(limit) is not int or not 1 <= limit <= maximum:
+        raise WorkflowContractError('audit page limit is outside its supported range')
+    data: dict[str, Any] = {'limit': limit}
+    if after is not None:
+        if target_cursor:
+            data['after'] = _identifier(after)
+        elif type(after) is not int or not 0 <= after <= 2**63 - 1:
+            raise WorkflowContractError('audit history cursor must be a nonnegative signed 64-bit integer')
+        else:
+            data['after'] = after
+    if through_version is not None:
+        data['through_version'] = _positive_version(through_version)
+        if not target_cursor and after is not None and after > through_version:
+            raise WorkflowContractError('audit cursor exceeds its selected snapshot')
+    return data
+
+
+def _decode(cls, value, bank, release):
+    try:
+        result = cls.from_dict(value)
+        if (result.bank_id, result.release_id) != (bank, release):
+            raise WorkflowContractError('selected audit response identity changed')
+        return result
+    except (WorkflowContractError, ValueError, TypeError, KeyError, AttributeError, RecursionError):
+        raise _invalid() from None
+
+
+def _page(cls, client, path, query, bank, release, *, protected=None):
+    result = _decode(cls, client._request('GET', path + '?' + urlencode(query)), bank, release)
+    if (len(result.items) > query['limit'] or
+            (query.get('through_version') is not None and result.through_version != query['through_version'])):
+        raise _invalid()
+    after = query.get('after')
+    if after is not None and any((item.target_id if isinstance(result, ReviewTargetPage) else item.version) <= after
+                                 for item in result.items):
+        raise _invalid()
+    if protected is not None and result.protected is not protected:
+        raise _invalid()
+    return result
+
+
+def release(client, bank, release_id) -> BankRelease:
+    return _decode(BankRelease, client._request('GET', _path(bank, release_id)), bank, release_id)
+
+
+def targets(client, bank, release_id, *, after=None, through_version=None, limit=20) -> ReviewTargetPage:
+    path = _path(bank, release_id) + '/targets'
+    query = _query(after=after, through_version=through_version, limit=limit, maximum=20, target_cursor=True)
+    return _page(ReviewTargetPage, client, path, query, bank, release_id)
+
+
+def history(client, bank, release_id, *, after=0, through_version=None, limit=None, protected=False) -> ReviewHistoryPage:
+    if type(protected) is not bool:
+        raise WorkflowContractError('protected history selection must be boolean')
+    maximum = 10 if protected else 100
+    path = _path(bank, release_id) + '/history'
+    query = _query(after=after, through_version=through_version, limit=maximum if limit is None else limit, maximum=maximum)
+    if protected:
+        query['protected'] = 'true'
+    return _page(ReviewHistoryPage, client, path, query, bank, release_id, protected=protected)
+
+
+def details(client, bank, release_id, target_id, *, after=0, through_version=None, limit=10) -> TargetReviewPage:
+    path = _path(bank, release_id) + '/targets/' + quote(_identifier(target_id), safe='') + '/reviews'
+    query = _query(after=after, through_version=through_version, limit=limit, maximum=10)
+    result = _page(TargetReviewPage, client, path, query, bank, release_id)
+    if result.target_id != target_id:
+        raise _invalid()
+    return result
+
+
+def write(client, bank: str, release_id: str | None, operation: Literal['create', 'contribute', 'adjudicate', 'transition'],
+          request: AuditRequest) -> ReviewOperationReceipt:
+    kind, suffix, event_kind, maximum = {
+        'create': (BankReleaseDeclaration, '', 'release_created', 262144),
+        'contribute': (ReviewContribution, '/contributions', 'contribution', 131072),
+        'adjudicate': (ReviewAdjudication, '/adjudications', 'adjudication', 16384),
+        'transition': (BankReleaseTransition, '/transitions', None, 16384),
+    }[operation]
+    if not isinstance(request, kind):
+        raise WorkflowContractError('audit operation needs its matching immutable request type')
+    path = _path(bank, release_id) + suffix
+    if operation == 'create':
+        assert isinstance(request, BankReleaseDeclaration)
+        release_id = request.release_id
+    assert release_id is not None
+    body = request.to_dict()
+    _key(request.idempotency_key)
+    if isinstance(request, ReviewContribution):
+        _identifier(request.target_id); _positive_version(request.expected_version)
+        if request.supersedes_contribution_id is not None:
+            _identifier(request.supersedes_contribution_id)
+        _bounded(body['judgment'], 65536)
+    _bounded(body, maximum)
+    # Existing Client serializes non-ASCII as escapes. Bound the actual request
+    # bytes as well as the decoded domain JSON, before any network work.
+    if len(json.dumps(body, separators=(',', ':'), allow_nan=False).encode()) > maximum:
+        raise WorkflowContractError('encoded audit request exceeds its route body limit')
+    try:
+        raw = client._request('POST', path, body, retry_key=request.idempotency_key)
+        try:
+            result = ReviewOperationReceipt.from_dict(raw)
+            expected_kind = request.action if isinstance(request, BankReleaseTransition) else event_kind
+            event = result.event
+            if ((event.bank_id, event.release_id, event.kind, result.operation_key) !=
+                    (bank, release_id, expected_kind, request.idempotency_key)):
+                raise WorkflowContractError('audit receipt belongs to another operation')
+            if not isinstance(request, BankReleaseDeclaration) and event.version != request.expected_version + 1:
+                raise WorkflowContractError('audit receipt version differs from the original write')
+            if isinstance(request, BankReleaseDeclaration) and event.version != 1:
+                raise WorkflowContractError('new release receipt must have version one')
+            if isinstance(request, (ReviewContribution, ReviewAdjudication)) and event.details.get('target_id') != request.target_id:
+                raise WorkflowContractError('audit receipt belongs to another target')
+            return result
+        except (WorkflowContractError, ValueError, TypeError, KeyError, AttributeError, RecursionError):
+            raise _invalid() from None
+    except HostedClientError as error:
+        raise AuditRequestError(error, bank_id=bank, release_id=release_id,
+                                operation=operation, request=request) from None

sphynx/_comparison_adapters.py

@@ -0,0 +1,113 @@
+"""Explicit projections of already verified permitted native comparisons.
+
+These functions neither authenticate nor compare evidence. Their backend caller
+must retain native verification and compatibility gates before projection.
+"""
+from __future__ import annotations
+
+from .comparison_views import ComparisonMetric, ComparisonPair, ComparisonView
+from .workflow_contracts import _thaw
+
+
+def _sources(backend, baseline, candidate, *, conditions=None):
+    sources = []
+    for index, ref in enumerate((baseline, candidate)):
+        binding = backend.reference(ref, "grading")
+        source = {"grading_id": binding.record_id, "run_id": binding.run_id,
+                  "status": binding.status, "trust_tier": binding.trust_tier,
+                  "metadata": _thaw(binding.metadata)}
+        if conditions is not None:
+            source["conditions"] = conditions[index]
+        sources.append(source)
+    return {"baseline": sources[0], "candidate": sources[1], "backend": backend.descriptor.to_dict()}
+
+
+def _view(sources, native, metrics=(), *, reason=None, status=None):
+    if status is None:
+        status = "incomplete" if any(item.status == "incomplete" for item in metrics) else "supported"
+    return ComparisonView(**sources, status=status, native=native, metrics=tuple(metrics), reason=reason)
+
+
+def _rerank_view(sources, native, specs):
+    if not native["compatible"]:
+        return _view(sources, native, status="incompatible", reason=native["reason"])
+    metrics = []
+    for identifier, data in native["metrics"].items():
+        spec = specs[identifier]
+        pairs = []
+        for row in data["per_case"]:
+            available = row["delta_b_minus_a"] is not None
+            pairs.append(ComparisonPair({"case_id": row["case_id"]}, row["value_a"], row["value_b"],
+                row["delta_b_minus_a"], "available" if available else
+                "undefined" if row["reason"] == "unsupported_query" else "missing", row["reason"]))
+        status = "supported" if data["complete"] else "incomplete" if data["missing_pair_count"] else "unavailable"
+        metrics.append(ComparisonMetric(identifier, data["unit"], data["direction"], "candidate_minus_baseline",
+            status, _thaw(spec.population),
+            {"policy_id": spec.comparison_policy, "aggregation": "equal_case_mean_of_paired_differences",
+             "sampling_unit": "case_id", "uncertainty": "not_estimated"},
+            delta=data["mean_delta"], observed_delta=data["observed_mean_delta"],
+            counts={key: data[key] for key in ("eligible_count", "paired_count", "missing_pair_count", "undefined_count")},
+            pairs=tuple(pairs), reason="no_eligible_observed_pairs" if status == "unavailable" else None))
+    return _view(sources, native, metrics)
+
+
+def _integrated_view(sources, native, specs):
+    metrics = []
+    for identifier, data in native["metrics"].items():
+        spec = specs[identifier]
+        pairs = tuple(ComparisonPair({"case_id": row["case_id"], "trial": row["trial"]},
+            row["baseline"], row["candidate"], row["delta"], row["availability"],
+            None if row["availability"] == "available" else
+            "baseline=" + str(row["baseline_reason"]) + "; candidate=" + str(row["candidate_reason"]),
+            {key: row[key] for key in ("baseline_availability", "candidate_availability", "baseline_reason", "candidate_reason")})
+            for row in native["pairs"] if row["criterion_id"] == identifier)
+        status = "incomplete" if data["excluded_pairs"] else "supported"
+        metrics.append(ComparisonMetric(identifier, spec.unit, spec.direction, "candidate_minus_baseline", status,
+            data["population"], {"policy_id": native["policy_id"],
+                "aggregation": "mean_available_trial_deltas_within_case_then_equal_case_mean",
+                "grouping_keys": ["case_id"], "paired_unit": ["case_id", "trial"],
+                "trials_independent": False, "uncertainty": "not_estimated"},
+            delta=data["candidate_minus_baseline"] if status == "supported" else None,
+            observed_delta=data["candidate_minus_baseline"],
+            counts={key: data[key] for key in ("planned_pairs", "eligible_pairs", "excluded_pairs", "eligible_cases",
+                                             "baseline_ungraded_trials", "candidate_ungraded_trials")}, pairs=pairs))
+    return _view(sources, native, metrics, reason=native["reason"])
+
+
+def _pipeline_view(sources, native, specs, reports):
+    metrics = []
+    for stage, values in native["delta"].items():
+        for name, delta in values.items():
+            identifier = "sphynx.pipeline." + stage + "." + name
+            spec = specs[identifier]
+            accounting = [report["metrics"]["stage_metric_accounting"][stage][name] for report in reports]
+            missing = any(item["missing_count"] for item in accounting)
+            status = "incomplete" if missing else "unavailable" if delta is None else "supported"
+            metrics.append(ComparisonMetric(identifier, spec.unit, spec.direction,
+                "candidate_minus_baseline", status,
+                {**_thaw(spec.population), "boundary": "native_stage_retained_inherited_pool",
+                 "eligibility": "native_side_specific_metric_eligibility"},
+                {"policy_id": spec.comparison_policy, "aggregation": "difference_of_native_stage_aggregates",
+                 "pair_details": "not_exposed", "uncertainty": "not_estimated",
+                 "timing_comparable": native["timing_comparable"]},
+                delta=delta if status == "supported" else None, observed_delta=delta,
+                counts={side + "_" + key: value for side, item in zip(("baseline", "candidate"), accounting)
+                        for key, value in item.items()},
+                reason="native_aggregate_unavailable" if status == "unavailable" else None))
+    return _view(sources, native, metrics)
+
+
+def _score_reliability_view(sources, native):
+    """Retain native cluster-bootstrap meaning; callers verify source bindings."""
+    partial = native["conditional_on_judged_subset"]
+    value = native["mean_improvement"]
+    status = "unavailable" if value is None else "incomplete" if partial else "supported"
+    metric = ComparisonMetric("brier_score", "squared_probability_error", "lower",
+        native["direction"], status,
+        {"reference_digest": native["reference_digest"], "label_policy": native["label_policy"],
+         "conditional_on_judged_subset": partial},
+        {"aggregation": native["aggregation"], "paired_unit": "query_id", "grouping_keys": ["cluster_id"],
+         "trials_independent": False}, delta=value if status == "supported" else None,
+        observed_delta=value, uncertainty=native["bootstrap"],
+        reason="no_observed_pairs" if status == "unavailable" else None)
+    return _view(sources, native, (metric,))

sphynx/_componentized_full_rag.py

@@ -0,0 +1,34 @@
+"""Controlled router/rewriter/generator diagnostic over an explicit context."""
+from copy import deepcopy
+from .contracts import ContractError
+
+
+def compose_full_rag(request,invoke):
+    """Call registered components; this boundary does not execute retrieval."""
+    stages={"router":None,"rewriter":None,"generator":None}
+    def call(kind,operation,payload):
+        result=invoke(kind,operation,deepcopy(payload))
+        if type(result) is not dict:raise ContractError("component output must be an object")
+        stages[kind]=deepcopy(result);return result
+    routing=call("router","route",{"task_id":request["case_id"],"query":request["query"],"conversation_context":request["conversation_context"]})
+    should_call=routing.get("should_call_rag")
+    if type(should_call) is not bool:raise ContractError("router must declare a boolean action")
+    rewritten=None;answer=None;citations=[];contexts=[];abstained=True
+    if should_call:
+        rewrite=call("rewriter","rewrite",{"task_id":request["case_id"],"query":request["query"]})
+        rewritten=rewrite.get("rewritten_query")
+        if type(rewritten) is not str or not rewritten.strip():raise ContractError("rewriter query is incomplete")
+        by_id={row["candidate_id"]:row for row in request["candidates"]}
+        contexts=list(request["context_candidate_ids"])
+        output=call("generator","generate",{"task_id":request["case_id"],"query":rewritten,
+            "contexts":[by_id[cid] for cid in contexts]})
+        answer=output.get("answer");abstained=output.get("abstained",False);citations=output.get("citations",[])
+        if type(answer) is not str or type(abstained) is not bool:raise ContractError("generator answer/action differs")
+    trace={"schema_version":"sable.rag.level3-trace.v1","task_id":request["case_id"],
+        "actual_rag_call_count":int(should_call),"call_outcome":"success" if should_call else "no_call",
+        "error":None,"as_uttered_query":request["query"],"rewritten_query":rewritten,
+        "retrieved_candidate_ids":contexts,"retrieved_context_ids":contexts,"handed_context_ids":contexts,
+        "answer":answer,"citations":citations,"abstained":abstained,"deferred":False,
+        "token_counts":{"prompt":0,"completion":0},"latency_ms":{}}
+    return {"schema_version":"sphynx.rag.full_rag.response.v1","case_id":request["case_id"],
+        "input_digest":request["input_digest"],"trace":trace,"stages":stages}