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

sphynx/learned_rerank.py

@@ -0,0 +1,267 @@
+"""Frozen learned-ranker and score-mapping inference, with no fitting API.
+
+T2/T7/T14/T17/T18 need an external verified ranker/calibrator. T19--T22
+consume frozen source artifacts. Raw probabilities remain distinct from rank.
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+
+from .contracts import ContractError
+from .integration_contracts import _wire, value_digest
+from .rerank_family_contracts import FrozenFittedState, SOURCE_PINS, family_configuration, finite, validate_signals
+from .statistical_rerank import mean, percentile, deviation, sigmoid
+
+FEATURE_NAMES = ('minilm_logit','dense_score','negative_dense_rank','title_query_match','section_query_match',
+    'passage_log_length','selected_window_position','source_authority','duplicate_cluster_size','retrieval_signal_disagreement')
+GATE_FEATURE_NAMES = ('a0_t19_rank_disagreement','a0_top_margin','a0_score_mad','missing_metadata_fraction','t19_ood_distance')
+FULL_CALIBRATION_FEATURES=('t2_score','negative_rank_fraction','gap_from_top','gap_to_previous','gap_to_next','query_score_standard_deviation')
+BOUNDED_CALIBRATION_FEATURES=('bounded_t2_score','bounded_robust_gap_to_next')
+METHODS = ('T2','T7','T14','T17','T18','T19','T20','T21','T22')
+METHOD_REGISTRY = MappingProxyType({name: MappingProxyType({'implementation':'available',
+    'fitted_state_required':True,'fitting_api':False,'historical_cohort_available':False,
+    'ranking_source':'T2' if name in ('T7','T14','T17','T18') else name,
+    'historical_state_available':name in ('T19','T20','T21','T22')}) for name in METHODS})
+
+
+def _linear_model(model, *, names=FEATURE_NAMES, intercept=False):
+    if not isinstance(model,Mapping):raise ContractError('frozen linear model is missing')
+    features=model.get('feature_names')
+    if not isinstance(features,(list,tuple)) or not features or len(set(features))!=len(features) or not set(features)<=set(names):
+        raise ContractError('linear model feature order is unknown or duplicate')
+    for field in ('means','standard_deviations','coefficients'):
+        values=model.get(field)
+        if not isinstance(values,(list,tuple)) or len(values)!=len(features):raise ContractError('linear model arrays differ from feature order')
+        for value in values:finite(value,field)
+    if any(v<=0 for v in model['standard_deviations']):raise ContractError('frozen standard deviations must be positive')
+    if intercept:finite(model.get('intercept'),'intercept')
+    return model
+
+
+def _linear(model, features, *, intercept=False):
+    return (model['intercept'] if intercept else 0.)+sum(
+        ((features[name] if features[name] is not None else 0.)-model['means'][i])/model['standard_deviations'][i]*model['coefficients'][i]
+        for i,name in enumerate(model['feature_names']))
+
+
+def _features(rows):
+    result=[]
+    for row in rows:
+        values=row.get('feature_values')
+        if not isinstance(values,Mapping) or set(values)!=set(FEATURE_NAMES):
+            raise ContractError('learned ranking requires exact declared label-free feature_values; missing metadata must be explicit null')
+        values=dict(values)
+        for key,value in values.items():
+            if value is not None:values[key]=finite(value,key)
+        # The source signals are authoritative for the three direct features.
+        for key,value in [('dense_score',row['dense_score']),('minilm_logit',row['minilm_logit']),('negative_dense_rank',-row['dense_rank'])]:
+            if values[key] != value:raise ContractError('learned direct feature differs from its frozen signal')
+        result.append(values)
+    return result
+
+
+def _a0(rows):
+    dense=_nextgen_zscores([r['dense_score'] for r in rows]);mini=_nextgen_zscores([r['minilm_logit'] for r in rows])
+    return [.45*x+.55*y for x,y in zip(dense,mini)]
+
+
+def _nextgen_zscores(values):
+    # This source convention differs from Cherry's scale=1 fallback: almost
+    # constant signals are exactly neutral in the next-generation family.
+    center=mean(values);std=deviation(values)
+    return [0.]*len(values) if std<=1e-12 else [(value-center)/std for value in values]
+
+
+def rank_geometry(scores, rows, *, bounded=False):
+    order=sorted(range(len(rows)),key=lambda i:(-scores[i],rows[i]['dense_rank']))
+    ordered=[scores[i] for i in order];center=percentile(ordered);mad=percentile([abs(x-center) for x in ordered]);std=deviation(ordered)
+    scale=mad if mad>1e-9 else std if std>1e-9 else 1.
+    result=[None]*len(rows);ranks=[0]*len(rows)
+    for index,position in enumerate(order):
+        current=ordered[index];previous=current if index==0 else ordered[index-1];nxt=current if index==len(order)-1 else ordered[index+1]
+        result[position]=[math.tanh(current/2.),math.tanh((current-nxt)/(scale*2.))] if bounded else [current,0. if len(order)<=1 else -index/(len(order)-1),ordered[0]-current,previous-current,current-nxt,std]
+        ranks[position]=index+1
+    return result,ranks
+
+
+def logistic_probabilities(calibrator, features):
+    if not isinstance(calibrator,Mapping):raise ContractError('frozen calibrator is missing')
+    names=calibrator.get('feature_names')
+    if not isinstance(names,(list,tuple)) or not names:raise ContractError('calibrator feature order is missing')
+    expected=FULL_CALIBRATION_FEATURES if features and len(features[0])==6 else BOUNDED_CALIBRATION_FEATURES
+    if tuple(names)!=expected:raise ContractError('calibrator feature order differs from source geometry')
+    _linear_model(calibrator,names=names,intercept=True)
+    if any(len(row)!=len(names) for row in features):raise ContractError('calibrator geometry shape differs')
+    lamb=calibrator.get('adaptive_tempering_lambda')
+    if lamb is not None and finite(lamb,'tempering lambda')<0:raise ContractError('negative tempering lambda')
+    output=[]
+    for row in features:
+        centered=sum((value-calibrator['means'][i])/calibrator['standard_deviations'][i]*calibrator['coefficients'][i] for i,value in enumerate(row))
+        temperature=1. if lamb is None else 1+lamb*(1-max(0.,min(1.,row[1])))
+        output.append(sigmoid(calibrator['intercept']+centered/temperature))
+    return output
+
+
+def _source_calibrator(calibrator, method):
+    variants={'T7':'T7_full','T14':'T14_bounded_two_feature','T17':'T17_margin_adaptive_tempering'}
+    if not isinstance(calibrator,Mapping) or calibrator.get('method')!='rank_aware_logistic' or calibrator.get('variant')!=variants[method]:
+        raise ContractError('calibrator method/variant differs from the selected source treatment')
+    if ('adaptive_tempering_lambda' not in calibrator or
+            (method=='T17') != (calibrator['adaptive_tempering_lambda'] is not None)):
+        raise ContractError('calibrator tempering policy differs from the selected source treatment')
+    return calibrator
+
+
+def robust_query_relative(scores, config):
+    fields={'robust_scale_epsilon','relative_score_temperature','constant_score_fallback'}
+    if not isinstance(config,Mapping) or set(config)!=fields:raise ContractError('query-relative policy differs from exact schema')
+    epsilon=finite(config['robust_scale_epsilon']);temperature=finite(config['relative_score_temperature'])
+    if epsilon<0 or temperature<=0 or config['constant_score_fallback'] not in ('normalized_rank','neutral'):raise ContractError('invalid query-relative policy')
+    center=percentile(scores);mad=percentile([abs(x-center) for x in scores]);std=deviation(scores)
+    if mad>epsilon:scale=mad;fallback='mad'
+    elif std>epsilon:scale=std;fallback='standard_deviation'
+    else:
+        values=[0. if len(scores)<=1 else 1-2*i/(len(scores)-1) for i in range(len(scores))] if config['constant_score_fallback']=='normalized_rank' else [0.]*len(scores)
+        return {'values':values,'center':center,'scale':0.,'fallback':config['constant_score_fallback']}
+    return {'values':[math.tanh((x-center)/scale/temperature) for x in scores],'center':center,'scale':scale,'fallback':fallback}
+
+
+def _isotonic(observations,target):
+    grouped={}
+    for score,label in observations:
+        weight,positives=grouped.get(score,(0,0));grouped[score]=(weight+1,positives+label)
+    blocks=[[score,score,*grouped[score]] for score in sorted(grouped)];index=0
+    while index<len(blocks)-1:
+        left,right=blocks[index],blocks[index+1]
+        if left[3]/left[2]<=right[3]/right[2]+1e-15:index+=1;continue
+        blocks[index:index+2]=[[left[0],right[1],left[2]+right[2],left[3]+right[3]]];index=max(0,index-1)
+    block=next((b for b in blocks if b[0]<=target<=b[1]),blocks[0] if target<blocks[0][0] else blocks[-1])
+    return block[3]/block[2]
+
+
+def predict_venn_abers(model,score):
+    """Original inductive Venn-Abers prediction; stored calibration only."""
+    if not isinstance(model,Mapping) or model.get('method')!='inductive_venn_abers' or model.get('label_mode') not in ('fully_labeled','known_judgments_only','positive_unlabeled_diagnostic'):
+        raise ContractError('unknown frozen Venn-Abers model/label mode')
+    observations=model.get('observations')
+    if not isinstance(observations,(list,tuple)) or not 1<=len(observations)<=10000:raise ContractError('bounded calibration observations required')
+    base=[]
+    for row in observations:
+        if not isinstance(row,Mapping) or type(row.get('label')) is not int or row['label'] not in (0,1):raise ContractError('invalid calibration observation')
+        base.append((finite(row.get('score')),row['label']))
+    score=finite(score);p0=_isotonic([*base,(score,0)],score);p1=_isotonic([*base,(score,1)],score);lower=max(0.,min(1.,min(p0,p1)));upper=max(lower,min(1.,max(p0,p1)));denominator=1-lower+upper
+    return {'p0':lower,'p1':upper,'probability':(lower+upper)/2 if denominator<=1e-12 else upper/denominator,'interval_width':upper-lower}
+
+
+def gate_features(rows,features,ranker,a0,t19):
+    pairs=[float((a0[i]>a0[j])-(a0[i]<a0[j]) != (t19[i]>t19[j])-(t19[i]<t19[j])) for i in range(len(rows)) for j in range(i+1,len(rows))]
+    distances=[math.sqrt(mean([((f[name] or 0.)-ranker['means'][i])**2/ranker['standard_deviations'][i]**2 for i,name in enumerate(ranker['feature_names'])])) for f in features]
+    metadata=('title_query_match','section_query_match','selected_window_position','source_authority','duplicate_cluster_size');ordered=sorted(a0,reverse=True);median=percentile(a0)
+    return {'a0_t19_rank_disagreement':mean(pairs),'a0_top_margin':ordered[0]-(ordered[1] if len(ordered)>1 else ordered[0]),'a0_score_mad':percentile([abs(x-median) for x in a0]),'missing_metadata_fraction':sum(f[key] is None for f in features for key in metadata)/(len(rows)*len(metadata)),'t19_ood_distance':mean(distances)}
+
+
+def decide_gate(model,features,config):
+    if not isinstance(model,Mapping) or model.get('method')!='bootstrap_regularized_logistic_gate':raise ContractError('frozen gate is missing')
+    fields={'minimum_improvement_probability','uncertainty_standard_deviations','maximum_ood_distance'}
+    if not isinstance(config,Mapping) or set(config)!=fields:raise ContractError('gate policy fields differ')
+    threshold=finite(config['minimum_improvement_probability']);uncertainty_scale=finite(config['uncertainty_standard_deviations']);ood=finite(config['maximum_ood_distance'])
+    if not 0<=threshold<=1 or uncertainty_scale<0 or ood<0:raise ContractError('gate policy bounds invalid')
+    members=model.get('members')
+    if not isinstance(members,(list,tuple)) or not 1<=len(members)<=500:raise ContractError('bounded frozen gate ensemble is missing')
+    probabilities=[]
+    for member in members:_linear_model(member,names=GATE_FEATURE_NAMES,intercept=True);probabilities.append(sigmoid(_linear(member,features,intercept=True)))
+    estimate=mean(probabilities);uncertainty=deviation(probabilities);lower=estimate-uncertainty_scale*uncertainty;reasons=[]
+    if lower<threshold:reasons.append('uncertain')
+    if features['t19_ood_distance']>ood:reasons.append('out_of_distribution')
+    return {'estimated_improvement_probability':estimate,'uncertainty_standard_deviation':uncertainty,'lower_confidence_score':lower,'gate_weight':0. if reasons else estimate,'fallback_to_a0':bool(reasons),'fallback_reasons':reasons}
+
+
+def score_learned_signals(signals,state,*,evaluation_cohort_digest,domain_id):
+    if not isinstance(state,FrozenFittedState) or state.method not in METHODS:raise ContractError('a verified frozen fitted state is required')
+    state.ensure_evaluation_cohort(evaluation_cohort_digest)
+    source=SOURCE_PINS['minilm-treatments.ts' if state.method in ('T2','T7','T14','T17','T18') else 'nextgen-rerankers.ts']
+    if state.provenance['source_digest']!=source:raise ContractError('fitted source implementation differs from the admitted family')
+    if not isinstance(domain_id,str) or not domain_id:raise ContractError('explicit domain identity required')
+    rows=validate_signals(signals,('minilm_logit',));features=_features(rows);payload=state.payload;method=state.method
+    expected_fields={'T2':{'ranker'},'T7':{'ranker','calibrator'},'T14':{'ranker','calibrator'},'T17':{'ranker','calibrator'},'T18':{'ranker','calibrator'},'T19':{'ranker'},'T20':{'ranker','calibrator','relative_policy'},'T21':{'ranker','gate','gate_policy','relative_policy','calibrator'},'T22':{'ranker','calibrator','domain_policy'}}
+    if set(payload)!=expected_fields[method]:raise ContractError('frozen learned payload differs from the method schema')
+    ranker=_linear_model(payload.get('ranker'));base=_a0(rows);learned=[_linear(ranker,f) for f in features]
+    if method in ('T19','T20','T21','T22') and ranker.get('method')!='a0_anchored_pairwise_residual':raise ContractError('T19 source residual method differs')
+    utility=learned if method in ('T2','T7','T14','T17','T18') else [x+y for x,y in zip(base,learned)]
+    diagnostics={'fitted_state_digest':state.artifact_digest,'lineage_authority':'caller_declared_unverified','refitting_performed':False};probabilities=None;intervals=None
+    if method in ('T7','T14','T17','T18'):
+        full,ranks=rank_geometry(utility,rows);bounded,_=rank_geometry(utility,rows,bounded=True)
+        if method=='T18':
+            blend=payload.get('calibrator')
+            if (not isinstance(blend,Mapping) or blend.get('target_ranks') not in ([4,5],(4,5))
+                    or blend.get('method')!='rank_4_to_5_probability_blend'
+                    or blend.get('variant')!='T18_T14_T7_boundary_blend'
+                    or blend.get('base_treatment')!='T14' or blend.get('boundary_treatment')!='T7'):
+                raise ContractError('T18 source policy only changes ranks four and five')
+            alpha=finite(blend.get('alpha'))
+            if not 0<=alpha<=1:raise ContractError('T18 alpha outside [0,1]')
+            t14=logistic_probabilities(_source_calibrator(blend.get('base_calibrator'),'T14'),bounded);t7=logistic_probabilities(_source_calibrator(blend.get('boundary_calibrator'),'T7'),full);probabilities=[(1-alpha)*x+alpha*y if 4<=rank<=5 else x for x,y,rank in zip(t14,t7,ranks)]
+        else:probabilities=logistic_probabilities(_source_calibrator(payload.get('calibrator'),method),full if method=='T7' else bounded)
+    elif method=='T20':
+        relative=robust_query_relative(utility,payload.get('relative_policy'));diagnostics['relative_fallback']=relative['fallback'];intervals=[predict_venn_abers(payload.get('calibrator'),x) for x in relative['values']];probabilities=[x['probability'] for x in intervals]
+    elif method=='T21':
+        gate=decide_gate(payload.get('gate'),gate_features(rows,features,ranker,base,utility),payload.get('gate_policy'));diagnostics['gate']=gate;weight=gate['gate_weight'];a,b=_nextgen_zscores(base),_nextgen_zscores(utility);utility=[(1-weight)*x+weight*y for x,y in zip(a,b)]
+        relative=robust_query_relative(utility,payload.get('relative_policy'));intervals=[predict_venn_abers(payload.get('calibrator'),x) for x in relative['values']];probabilities=[x['probability'] for x in intervals]
+    elif method=='T22':
+        policy=payload.get('domain_policy')
+        if (not isinstance(policy,Mapping) or set(policy)!={'in_distribution_domains','ranking_policy'}
+                or policy['ranking_policy']!='t19_in_distribution_a0_otherwise'
+                or not isinstance(policy['in_distribution_domains'],(list,tuple)) or not policy['in_distribution_domains']
+                or any(not isinstance(x,str) or x not in ('sable','scifact','nfcorpus') for x in policy['in_distribution_domains'])
+                or len(set(policy['in_distribution_domains']))!=len(policy['in_distribution_domains'])
+                or domain_id not in ('sable','scifact','nfcorpus')):raise ContractError('unknown T22 domain policy')
+        intervals=[predict_venn_abers(payload.get('calibrator'),x) for x in utility];probabilities=[x['probability'] for x in intervals];use_learned=domain_id in policy['in_distribution_domains'];diagnostics['ranking_path']='T19' if use_learned else 'A0';utility=utility if use_learned else base
+    fields={'ranking_utility':{'kind':'utility','values':utility},'raw_minilm_logit':{'kind':'utility','values':[r['minilm_logit'] for r in rows]}}
+    if probabilities is not None:
+        if method in ('T20','T21','T22') and payload['calibrator'].get('label_mode')!=state.provenance['label_mode']:raise ContractError('calibrator label mode differs from frozen provenance')
+        kind='diagnostic' if state.provenance['label_mode']=='positive_unlabeled_diagnostic' else 'probability';fields['evidence_probability']={'kind':kind,'values':probabilities,'probability_target':'frozen_strong_relevance' if kind=='probability' else None}
+    if intervals is not None:
+        for key in ('p0','p1','interval_width'):fields['venn_abers_'+key]={'kind':'diagnostic','values':[row[key] for row in intervals]}
+    if any(not math.isfinite(v) for field in fields.values() for v in field['values']):raise ContractError('derived learned score is not finite')
+    return {'schema_version':'sphynx.rerank-family.scores.v1','method':method,'method_version':'v1','candidate_ids':[r['candidate_id'] for r in rows],'fields':fields,'diagnostics':diagnostics,'reference_sources':dict(SOURCE_PINS),'inference_observed':False}
+
+
+class LearnedScorer:
+    """A frozen model-logit and metadata composition behind the legacy protocol."""
+    def __init__(self,state,*,minilm_scorer,feature_provider,evaluation_cohort_digest,domain_id):
+        if not isinstance(state,FrozenFittedState):raise ContractError('frozen fitted state required')
+        state.ensure_evaluation_cohort(evaluation_cohort_digest)
+        self.state,self.minilm_scorer,self.feature_provider=state,minilm_scorer,feature_provider
+        self.evaluation_cohort_digest,self.domain_id=evaluation_cohort_digest,domain_id
+        self._configuration=family_configuration(state.method,LEARNED_IMPLEMENTATION_DIGEST,
+            parameters={'evaluation_cohort_digest':evaluation_cohort_digest,'domain_id':domain_id},
+            scorers={'minilm':minilm_scorer,'features':feature_provider},fitted_state=state)
+    @property
+    def configuration(self):return self._configuration
+    def score_fields(self,request):
+        from .model_adapters import request_pairs
+        request_pairs(request)
+        frozen=self.configuration.to_dict()['parameters'];expected=frozen['source_scorers']
+        if (self.state.method!=frozen['method'] or self.state.artifact_digest!=frozen['fitted_state']['artifact_digest']
+                or _wire(self.state.provenance)!=frozen['fitted_state']['provenance']
+                or self.evaluation_cohort_digest!=frozen['parameters']['evaluation_cohort_digest'] or self.domain_id!=frozen['parameters']['domain_id']):raise ContractError('frozen learned configuration changed')
+        if self.minilm_scorer.configuration.to_dict()!=expected['minilm'] or self.feature_provider.configuration.to_dict()!=expected['features']:raise ContractError('frozen source/feature provider configuration changed')
+        response=self.minilm_scorer(request);supplied=self.feature_provider(request)
+        if response.get('schema_version')!='sphynx.rag.rerank.response.v1' or response.get('query_id')!=request['query_id'] or response.get('pool_digest')!=request['pool_digest']:raise ContractError('model scorer request identity differs')
+        scores=response.get('scores');values={r.get('candidate_id'):r.get('ranking_score') for r in scores} if isinstance(scores,list) and all(isinstance(r,dict) for r in scores) else {}
+        ids={r['candidate_id'] for r in request['candidates']}
+        if not isinstance(supplied,Mapping) or set(supplied)!=ids or set(values)!=ids or len(scores)!=len(ids):raise ContractError('model/feature provider membership differs')
+        rows=[{'candidate_id':r['candidate_id'],'dense_score':r['dense_score'],'dense_rank':r['dense_rank'],'minilm_logit':values[r['candidate_id']],'feature_values':supplied[r['candidate_id']]} for r in request['candidates']]
+        return score_learned_signals(rows,self.state,evaluation_cohort_digest=self.evaluation_cohort_digest,domain_id=self.domain_id)
+    def __call__(self,request):
+        result=self.score_fields(request)
+        return {'schema_version':'sphynx.rag.rerank.response.v1','query_id':request['query_id'],'pool_digest':request['pool_digest'],'scores':[{'candidate_id':cid,'ranking_score':value} for cid,value in zip(result['candidate_ids'],result['fields']['ranking_utility']['values'])]}
+
+
+def create_learned_scorer(state,*,minilm_scorer,feature_provider,evaluation_cohort_digest,domain_id):
+    return LearnedScorer(state,minilm_scorer=minilm_scorer,feature_provider=feature_provider,evaluation_cohort_digest=evaluation_cohort_digest,domain_id=domain_id)
+LEARNED_IMPLEMENTATION_DIGEST=value_digest({p.name:'sha256:'+hashlib.sha256(p.read_bytes()).hexdigest() for p in (Path(__file__),Path(__file__).with_name('rerank_family_contracts.py'),Path(__file__).with_name('statistical_rerank.py'))})

sphynx/legacy_full_rag.py

@@ -0,0 +1,67 @@
+"""Mechanical same-output audit of the old Cherry answer-only capture.
+
+This imports historical verdicts as declared history, not fresh semantic truth.
+No private answers, source text, token, URLs or credentials appear in the report.
+The missing retrieval/context trace cannot be reconstructed from these answers.
+"""
+from pathlib import Path
+import statistics
+from fractions import Fraction
+from ._track_capture import byte_digest,strict_json
+from .pipeline import _require,_number
+
+
+def audit_legacy_cherry_full_rag(capture_path,scorecard_path,reference_path,*,expected_capture_digest,
+        expected_scorecard_digest,expected_reference_digest):
+    values=[];bindings=[]
+    for path,digest in ((capture_path,expected_capture_digest),(scorecard_path,expected_scorecard_digest),(reference_path,expected_reference_digest)):
+        raw=Path(path).read_bytes();_require(byte_digest(raw)==digest,"legacy artifact hash differs")
+        values.append(strict_json(raw));bindings.append({"digest":digest,"size_bytes":len(raw)})
+    capture,scorecard,reference=values
+    _require(capture.get("schema")=="cherry-full-rag-run/v1" and scorecard.get("schema")=="cherry-full-rag-scorecard/v1"
+        and reference.get("suite_id")=="cherry-full-rag-v1" and reference.get("evaluation_level")==3,"legacy schema differs")
+    _require(type(capture.get("cases")) is list and type(reference.get("cases")) is list
+        and type(scorecard.get("verdicts")) is list,"legacy case arrays are required")
+    answers={row.get("query_index"):row for row in capture["cases"] if type(row) is dict}
+    refs={row.get("query_index"):row for row in reference["cases"] if type(row) is dict}
+    verdicts={row.get("case_id"):row for row in scorecard["verdicts"] if type(row) is dict}
+    _require(answers and len(answers)==len(capture["cases"]) and len(refs)==len(reference["cases"])
+        and len(verdicts)==len(scorecard["verdicts"]) and set(answers)==set(refs)
+        and all(type(key) is int and key>=0 for key in answers),"legacy query membership differs")
+    _require(set(verdicts)=={row.get("case_id") for row in refs.values()},"legacy verdict membership differs")
+    timings=[];rows=[];counts={"pass":0,"partial":0,"fail":0}
+    for index in sorted(answers):
+        answer=answers[index];truth=refs[index];verdict=verdicts[truth["case_id"]].get("verdict")
+        _require(verdict in counts and type(answer.get("query")) is str and type(answer.get("answer")) is str
+            and type(answer.get("timed_out")) is bool,"legacy answer/verdict fields differ")
+        timing=answer.get("observed_first_text_latency_ms")
+        _require(_number(timing) and timing>=0,"legacy browser timing differs")
+        counts[verdict]+=1;timings.append(timing)
+        rows.append({"case_id":truth["case_id"],"query_index":index,"query_digest":byte_digest(answer["query"].encode()),
+            "answer_digest":byte_digest(answer["answer"].encode()),"legacy_verdict":verdict,"timed_out":answer["timed_out"],
+            "browser_first_text_wall_ms":timing,"semantic_regraded":False})
+    n=len(rows);weighted=(counts["pass"]+.5*counts["partial"])/n
+    grading=scorecard.get("grading")
+    expected={"strict_pass_count":counts["pass"],"partial_count":counts["partial"],"fail_count":counts["fail"],"case_count":n,
+        "strict_pass_rate":counts["pass"]/n,"substantively_correct_or_partial_rate":(counts["pass"]+counts["partial"])/n,"weighted_score":weighted}
+    _require(type(grading) is dict and all(grading.get(key)==value for key,value in expected.items())
+        and grading.get("pass_weight")==1 and grading.get("partial_weight")==.5 and grading.get("fail_weight")==0,
+        "legacy declared grade arithmetic differs")
+    ordered=sorted(timings);position=Fraction((n-1)*95,100);lower=int(position)
+    # The retained report records the decimal linear quantile. Exact rational
+    # interpolation avoids introducing a binary .95 rounding artifact here.
+    p95=float(Fraction(str(ordered[lower]))+(Fraction(str(ordered[min(lower+1,n-1)]))-Fraction(str(ordered[lower])))*(position-lower))
+    latency={"count":n,"mean":sum(timings)/n,"p50":statistics.median(timings),"p95_linear":p95,"min":min(timings),"max":max(timings)}
+    _require(type(scorecard.get("latency_ms")) is dict and all(scorecard["latency_ms"].get(key)==value for key,value in latency.items()),
+        "legacy declared latency arithmetic differs")
+    # All cases share one historical deployed-agent session. The independent
+    # trace/review contracts required by the new SDK are absent from this schema.
+    return {"schema_version":"sphynx.rag.legacy-opaque-audit.v1","status":"partial",
+        "execution_mode":"saved_capture_audit","new_candidate_execution":False,"case_count":n,
+        "capture":bindings[0],"legacy_scorecard":bindings[1],"reference":bindings[2],"cases":rows,
+        "legacy_declared_grading":expected,"browser_first_text_latency_ms":latency,
+        "latency_scope":"query-submit-to-first-rendered-text_not_model_ttft","independent_per_query":False,
+        "semantic_review_verified":False,"complete_trace_eligible":False,
+        "blockers":["retrieval_and_handoff_trace_missing","capture_bound_independent_review_missing","independent_query_reset_missing"],
+        "current_full_rag_metrics":{key:None for key in ("rag_call_precision","rag_call_recall","rewrite_preservation",
+            "evidence_handoff_completeness","answer_completeness","faithfulness","unsupported_claim_rate","citation_support")}}