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

sphynx/stage_contracts.py

@@ -0,0 +1,199 @@
+"""Neutral replacement identities and permitted, occurrence-bound stage evidence.
+
+These views do not authenticate bytes or authorize access. A backend verifies
+the native capture and its access policy before projecting a selected stage.
+"""
+from __future__ import annotations
+
+from dataclasses import InitVar, dataclass, field
+import hashlib
+import json
+import re
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from .assessment_contracts import EvidenceView, _freeze_json, _mapping, _thaw
+from .workflow_contracts import PayloadSchema, WorkflowContractError, _text, contract_digest
+
+STAGE_EVIDENCE_CAPABILITY = "sphynx.stage-evidence.v1"
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_PROJECTED = object()
+
+
+class StageContractError(WorkflowContractError):
+    """An invalid selection, replacement or stage projection."""
+
+
+def _digest(value, name):
+    if type(value) is not str or not _DIGEST.fullmatch(value):
+        raise StageContractError(name + " must be a complete sha256 digest")
+
+
+def _positive(value, name):
+    if type(value) is not int or value < 1:
+        raise StageContractError(name + " must be a positive integer")
+
+
+def _projection_digest(value):
+    raw = json.dumps(_thaw(value), ensure_ascii=False, sort_keys=True,
+                     separators=(",", ":"), allow_nan=False).encode("utf-8")
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+@dataclass(frozen=True)
+class StageDefinition:
+    """One logical stage with exact implementation/configuration and I/O IDs."""
+
+    stage_id: str
+    implementation_id: str
+    version: str
+    input_schema_id: str
+    output_schema_id: str
+    implementation_digest: str
+    configuration_digest: str
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        for name in ("stage_id", "implementation_id", "version", "input_schema_id", "output_schema_id"):
+            _text(getattr(self, name), name)
+        for name in ("implementation_digest", "configuration_digest"):
+            _digest(getattr(self, name), name)
+        object.__setattr__(self, "metadata", _mapping(self.metadata, "stage metadata"))
+
+    @property
+    def identity_digest(self):
+        return contract_digest(self.to_dict())
+
+    def to_dict(self):
+        return {"stage_id": self.stage_id, "implementation_id": self.implementation_id,
+                "version": self.version, "input_schema_id": self.input_schema_id,
+                "output_schema_id": self.output_schema_id,
+                "implementation_digest": self.implementation_digest,
+                "configuration_digest": self.configuration_digest, "metadata": _thaw(self.metadata)}
+
+
+@dataclass(frozen=True)
+class StageReplacement:
+    """An explicit change at one compatible stage; it does not execute a swap."""
+
+    stage_id: str
+    baseline: StageDefinition
+    replacement: StageDefinition
+
+    def __post_init__(self):
+        _text(self.stage_id, "stage_id")
+        if not isinstance(self.baseline, StageDefinition) or not isinstance(self.replacement, StageDefinition):
+            raise StageContractError("replacement requires exact stage definitions")
+        if self.baseline.stage_id != self.stage_id or self.replacement.stage_id != self.stage_id:
+            raise StageContractError("replacement stage identity differs")
+        if (self.baseline.input_schema_id, self.baseline.output_schema_id) != (
+                self.replacement.input_schema_id, self.replacement.output_schema_id):
+            raise StageContractError("replacement input/output schemas are incompatible")
+        if self.baseline.identity_digest == self.replacement.identity_digest:
+            raise StageContractError("replacement must change stage identity")
+
+    def require_baseline(self, current: StageDefinition):
+        if not isinstance(current, StageDefinition) or current.identity_digest != self.baseline.identity_digest:
+            raise StageContractError("replacement baseline identity drift")
+
+    def to_dict(self):
+        return {"stage_id": self.stage_id, "baseline": self.baseline.to_dict(),
+                "replacement": self.replacement.to_dict()}
+
+
+@dataclass(frozen=True)
+class StageSelector:
+    """Select one exact stage occurrence within one case/trial/attempt.
+
+    No wildcard or inferred 'latest attempt' is allowed. Different evidence roles
+    may be returned for that occurrence; their native visibility remains binding.
+    """
+
+    case_id: str
+    trial: int
+    attempt: int
+    stage_id: str
+    occurrence: int = 1
+
+    def __post_init__(self):
+        _text(self.case_id, "case_id")
+        _text(self.stage_id, "stage_id")
+        for name in ("trial", "attempt", "occurrence"):
+            _positive(getattr(self, name), name)
+
+    def to_dict(self):
+        return {"case_id": self.case_id, "trial": self.trial, "attempt": self.attempt,
+                "stage_id": self.stage_id, "occurrence": self.occurrence}
+
+
+@dataclass(frozen=True)
+class StageEvidence:
+    """A permitted projection, distinct from its native artifact byte identity."""
+
+    selector: StageSelector
+    evidence: EvidenceView
+    projection: Any = None
+    projection_digest: str | None = None
+    projection_schema: Mapping[str, Any] | None = None
+    reason: str | None = None
+    _token: InitVar[object] = None
+
+    def __post_init__(self, _token):
+        if not isinstance(self.selector, StageSelector) or not isinstance(self.evidence, EvidenceView):
+            raise StageContractError("stage evidence requires a selector and EvidenceView")
+        if (self.evidence.case_id, self.evidence.step_id) != (self.selector.case_id, self.selector.stage_id):
+            raise StageContractError("stage evidence case/stage binding differs")
+        if self.evidence.availability == "available":
+            if _token is not _PROJECTED or self.projection_schema is None:
+                raise StageContractError("available stage evidence requires a validated projection")
+            frozen = _freeze_json(self.projection, "stage projection")
+            _digest(self.projection_digest, "projection_digest")
+            if self.projection_digest != _projection_digest(frozen):
+                raise StageContractError("stage projection digest differs")
+            schema = _mapping(self.projection_schema, "projection schema")
+            if set(schema) != {"schema_id", "version", "implementation_id"}:
+                raise StageContractError("stage projection requires exact schema identity")
+            for name, value in schema.items():
+                _text(value, "projection " + name)
+            object.__setattr__(self, "projection", frozen)
+            object.__setattr__(self, "projection_schema", schema)
+        elif (self.projection is not None or self.projection_digest is not None
+              or self.projection_schema is not None or self.reason is None):
+            raise StageContractError("unavailable stage evidence requires a reason and no projected value")
+        if self.reason is not None:
+            _text(self.reason, "stage evidence reason")
+
+    @classmethod
+    def projected(cls, selector: StageSelector, evidence: EvidenceView, projection: Any, *,
+                  schema: PayloadSchema):
+        """Validate permitted content explicitly; do not read or verify storage."""
+        if not isinstance(schema, PayloadSchema):
+            raise StageContractError("stage projection requires a PayloadSchema")
+        validated = schema.validate(projection)
+        return cls(selector, evidence, validated, _projection_digest(validated),
+                   {"schema_id": schema.schema_id, "version": schema.version,
+                    "implementation_id": schema.implementation_id}, _token=_PROJECTED)
+
+    @classmethod
+    def unavailable(cls, selector: StageSelector, evidence: EvidenceView, *, reason: str):
+        """Keep missing/skipped/unretained evidence explicit; no synthetic value."""
+        if not isinstance(evidence, EvidenceView) or evidence.availability == "available":
+            raise StageContractError("unavailable stage evidence needs an unavailable EvidenceView")
+        return cls(selector, evidence, reason=reason)
+
+    @property
+    def availability(self):
+        return self.evidence.availability
+
+    def to_dict(self):
+        return {"schema_version": "sphynx.stage-evidence.v1",
+                "selector": self.selector.to_dict(), "evidence": self.evidence.to_dict(),
+                "projection": _thaw(self.projection), "projection_digest": self.projection_digest,
+                "projection_schema": None if self.projection_schema is None else _thaw(self.projection_schema),
+                "reason": self.reason}
+
+
+@runtime_checkable
+class StageEvidenceBackend(Protocol):
+    """Optional backend capability; selection is not a permission grant."""
+
+    def stage_evidence(self, native_ref: Any, selector: StageSelector) -> tuple[StageEvidence, ...]: ...

sphynx/statistical_catalog_data.py

@@ -0,0 +1,53 @@
+"""Content-free statistical/Cherry method discovery; no algorithm/ML imports."""
+from types import MappingProxyType
+from .catalog import CandidateDescriptor
+from .integration_contracts import ScoreField
+
+_SOURCE='sha256:58cbcaff4f548bddee562a2f4680cf033d6e10c58288d37f79bc5eb19bec655d'
+_BASE=('S1','S2','S3','S4','S5a','S5b','S5c','A0','A0-A','A0-B','Dense-only','MiniLM-only',
+    'MiniLM-robust-mean','MiniLM-robust-dominance','MiniLM-RRF','Jina-only','Jina-60/40',
+    'Jina-RRF','Jina-E1','Jina-E3','Jina-E4-no-lexical','Jina-E4','Guarded-Jina-E2',
+    'S6','S6-E1','S6-E2','S6-E3','S6-E4','S7')
+METHOD_NAMES=_BASE+('Jina-E2-dense-anchored','Jina-E2','Jina-E2-wide','Jina-E2-model-anchored')+tuple(
+    f'MiniLM-W{x:02d}/{100-x:02d}' for x in range(90,0,-10))+tuple(
+    f'Jina-W{x:02d}/{100-x:02d}' for x in range(90,0,-10) if x!=60)
+_ALIASES={'S6':'Jina-60/40','S6-E1':'Jina-E1','S6-E2':'Jina-E2','S6-E3':'Jina-E3','S6-E4':'Jina-E4','S7':'Jina-RRF',
+    'A0-A':'A0','A0-B':'A0','MiniLM-robust-dominance':'MiniLM-robust-mean'}
+_DISPLAY={'A0':'raw_minilm_sigmoid_diagnostic','A0-A':'raw_fused_utility','Dense-only':'clipped_dense_score',
+    'S1':'clipped_dense_score','S2':'bounded_relative_tanh','S3':'bounded_relative_tanh',
+    'MiniLM-robust-mean':'bounded_relative_tanh','MiniLM-RRF':'bounded_relative_tanh'}
+METHOD_METADATA=MappingProxyType({name:MappingProxyType({
+    'method':name,'ranking_alias_of':_ALIASES.get(name),
+    'display_convention':_DISPLAY.get(name,'original_typescript_erf' if name.startswith('S') else 'original_cherry_gaussian_cdf'),
+    'fitted_selection_required':name in ('S5a','S5b','S5c'),
+    'model_inference_performed_by_fusion':False,
+    'historical_cherry_37_parity':not name.startswith('S'),
+    'fresh_guarded_confirmation_policy_ported':False,
+}) for name in METHOD_NAMES})
+
+
+def _fields(name):
+    common=(ScoreField('ranking_utility','utility','higher','ranking_utility'),)
+    if name=='A0':return common+(ScoreField('raw_model_sigmoid','diagnostic','higher','sigmoid_value'),)
+    if name=='A0-A':return common+(ScoreField('display_utility','utility','higher','ranking_utility'),)
+    return common+(ScoreField('pool_relative_strength','pool_relative','higher','pool_relative_strength'),)
+
+
+def _prerequisites(name):
+    required=['complete aligned dense/model source signals and frozen scorer configuration',
+        'separately authorized dataset and original evaluation policy; discovery grants no data access']
+    if name in ('S5a','S5b','S5c'):required.append('external frozen development-selection weight and digest; no selection is fitted automatically')
+    if name in ('Jina-E4','S6-E4'):required.append('original-corpus BM25 vectors for Cherry parity; candidate-pool BM25 is a distinct index policy')
+    if name=='Guarded-Jina-E2':required.append('SciPy linear_sum_assignment when the original ambiguity trigger fires')
+    if name.startswith('S'):required.append('original TypeScript display convention; aliases share ranking but can have different displays')
+    return tuple(required)
+
+
+CANDIDATES=tuple(CandidateDescriptor(
+    candidate_id='statistical-'+name.replace('/','-')+'-v1',track='rerank',
+    interface_version='sphynx.rerank-family.v1',source_digest=_SOURCE,
+    supported_dataset_ids=(),execution_modes=('recorded','trusted_local'),implementation_status='available',
+    reason='Pure fusion code is available. Neural scores/state/data are caller prerequisites; no hosted admission is implied. Historical Cherry parity reuses recorded scores.',
+    local_prerequisites=_prerequisites(name),dependencies=('scipy',) if name=='Guarded-Jina-E2' else (),
+    score_fields=_fields(name),supported_python=('3.11','3.12','3.13','3.14'),
+) for name in METHOD_NAMES)

sphynx/statistical_rerank.py

@@ -0,0 +1,232 @@
+"""Source-pinned statistical and Cherry score-fusion algorithms.
+
+No model is loaded here. Model callbacks are explicit and already carry frozen
+model/recording identity. Display strength is never called a probability.
+"""
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+
+from .contracts import ContractError
+from .integration_contracts import value_digest
+from .rerank_family_contracts import SOURCE_PINS, family_configuration, finite, validate_signals
+
+EPSILON = 1e-12
+E2_WEIGHTS = (.8, .7, .6, .5, .4)
+E2_BANDS = {"Jina-E2-dense-anchored": (.9,.8,.7,.6,.5), "Jina-E2": E2_WEIGHTS,
+    "Jina-E2-wide": (.9,.8,.7,.6,.5,.4,.3,.2,.1), "Jina-E2-model-anchored": (.4,.3,.2,.1,0.)}
+BASE_METHODS = ("S1","S2","S3","S4","S5a","S5b","S5c","A0","A0-A","A0-B","Dense-only","MiniLM-only","MiniLM-robust-mean","MiniLM-robust-dominance","MiniLM-RRF","Jina-only","Jina-60/40","Jina-RRF","Jina-E1","Jina-E3","Jina-E4-no-lexical","Jina-E4","Guarded-Jina-E2","S6","S6-E1","S6-E2","S6-E3","S6-E4","S7")
+METHODS = BASE_METHODS + tuple(E2_BANDS) + tuple(f"MiniLM-W{x:02d}/{100-x:02d}" for x in range(90,0,-10)) + tuple(f"Jina-W{x:02d}/{100-x:02d}" for x in range(90,0,-10) if x != 60)
+METHOD_REGISTRY = MappingProxyType({name: MappingProxyType({"implementation": "available", "weights_bundled": False,
+    "fitted_selection_required": name in ("S5a","S5b","S5c"), "optional_dependency": "scipy" if name == "Guarded-Jina-E2" else None}) for name in METHODS})
+
+
+def mean(values): return sum(values) / len(values) if values else 0.
+def percentile(values, fraction=.5):
+    ordered=sorted(values);position=fraction*(len(ordered)-1);lower=math.floor(position);upper=math.ceil(position)
+    return ordered[lower] if lower==upper else ordered[lower]+(ordered[upper]-ordered[lower])*(position-lower)
+def deviation(values):
+    average=mean(values);return math.sqrt(mean([(value-average)**2 for value in values]))
+def sigmoid(value):
+    return 1/(1+math.exp(-value)) if value>=0 else math.exp(value)/(1+math.exp(value))
+def robust_scale(values):
+    center=percentile(values);mad=percentile([abs(value-center) for value in values]);std=deviation(values)
+    return 1.4826*mad if mad>EPSILON else std if std>EPSILON else 1.
+def robust_normalize(values):
+    values=[finite(v) for v in values]
+    if not values:return []
+    center=percentile(values);scale=robust_scale(values)
+    return [max(-3.,min(3.,(value-center)/scale)) for value in values]
+def zscores(values):
+    center=mean(values);std=deviation(values);scale=std if std>EPSILON else 1.
+    return [(value-center)/scale for value in values]
+def _ts_cdf(value):
+    # Preserve the original TS approximation exactly, including its argument.
+    absolute=abs(value);t=1/(1+.3275911*absolute)
+    polynomial=((((1.061405429*t-1.453152027)*t+1.421413741)*t-.284496736)*t+.254829592)*t
+    erf=1-polynomial*math.exp(-absolute*absolute)
+    return .5*(1+(-erf if value<0 else erf))
+def dominance(values, *, reference="statistical.ts"):
+    if len(values)==1:return [.5]
+    scale=robust_scale(values);cdf=_ts_cdf if reference=="statistical.ts" else lambda value:.5*(1+math.erf(value/math.sqrt(2)))
+    return [mean([cdf((current-other)/(math.sqrt(2)*scale)) for j,other in enumerate(values) if i!=j]) for i,current in enumerate(values)]
+def bounded_relative(values):return [.5+.45*math.tanh(value/2) for value in robust_normalize(values)]
+
+
+def candidate_pool_bm25(signals):
+    query=signals[0].get("query_text")
+    if not isinstance(query,str) or not query or any(row.get("query_text")!=query or not row.get("passage_text") for row in signals):
+        raise ContractError("lexical fusion requires one shared query and every passage")
+    token=lambda text:re.findall('[a-z0-9]+',text.lower())
+    terms=set(token(query));docs=[token(row['passage_text']) for row in signals];average=mean([len(doc) for doc in docs]) or 1.
+    scores=[]
+    for doc in docs:
+        score=0.
+        for term in sorted(terms):
+            frequency=doc.count(term)
+            if not frequency:continue
+            df=sum(term in other for other in docs);idf=math.log(1+(len(docs)-df+.5)/(df+.5))
+            score+=idf*frequency*2.2/(frequency+1.2*(1-.75+.75*len(doc)/average))
+        scores.append(score)
+    return scores
+
+
+def _agreement(left,right):
+    if abs(left)<=EPSILON and abs(right)<=EPSILON:return 1.
+    if abs(left)<=EPSILON or abs(right)<=EPSILON:return .5
+    return float((left>0)==(right>0))
+def _pair_agreement(left,right):return mean([_agreement(left[i]-left[j],right[i]-right[j]) for i in range(len(left)) for j in range(i+1,len(left))])
+def _signal_confidence(values,peers,penalty=0.):
+    if len(values)<=1:return 1.
+    normalized=robust_normalize(values);exps=[math.exp(v-max(normalized)) for v in normalized];total=sum(exps);p=[v/total for v in exps]
+    concentration=1+sum(v*math.log(v) for v in p)/math.log(len(p));ordered=sorted(normalized,reverse=True)
+    return max(0.,min(1.,(.3*concentration+.25*math.tanh(max(0.,ordered[0]-ordered[1]))+.2*(1-math.exp(-deviation(normalized)))+.25*mean([_pair_agreement(values,peer) for peer in peers]))*(1-penalty)))
+def adaptive_weights(signals,minilm_weight=.55,lexical_weight=.2):
+    dense=[r['dense_score'] for r in signals];mini=[r['minilm_logit'] for r in signals];lexical=candidate_pool_bm25(signals)
+    saturation=mean([float(sigmoid(v)<=.05 or sigmoid(v)>=.95) for v in mini])
+    confidence={'dense':_signal_confidence(dense,[mini,lexical]),'minilm':_signal_confidence(mini,[dense,lexical],.5*saturation),'lexical':_signal_confidence(lexical,[dense,mini])}
+    base={'dense':(1-lexical_weight)*(1-minilm_weight),'minilm':(1-lexical_weight)*minilm_weight,'lexical':lexical_weight}
+    raw={k:base[k]*(.5+confidence[k]) for k in base};active=list(base);remaining=1.;result={}
+    while active:
+        total=sum(raw[k] for k in active);provisional={k:remaining/len(active) if total<=EPSILON else remaining*raw[k]/total for k in active}
+        below=next((k for k in active if provisional[k]<.2-EPSILON),None)
+        above=next((k for k in active if provisional[k]>.6+EPSILON),None)
+        key=below or above
+        if key is None:result.update(provisional);break
+        result[key]=.2 if below else .6;remaining-=result[key];active.remove(key)
+    return result,confidence
+
+
+def _ranks(values,signals,*,pool_order=False):
+    ordered=sorted(range(len(values)),key=lambda i:(-values[i],i if pool_order else signals[i]['dense_rank']))
+    output=[0]*len(values)
+    for rank,index in enumerate(ordered,1):output[index]=rank
+    return output
+def _convex(dense,model,weight,*,robust=False):
+    normalize=robust_normalize if robust else zscores;d,m=normalize(dense),normalize(model)
+    return [weight*x+(1-weight)*y for x,y in zip(d,m)]
+def _e2(dense,jina,signals,weights=E2_WEIGHTS,*,robust=False):
+    parts=[_ranks(_convex(dense,jina,w,robust=robust),signals,pool_order=True) for w in weights]
+    return [mean([1/(60+part[i]) for part in parts]) for i in range(len(dense))]
+def bounded_merge(a0,e2,dense,jina,signals,maximum_movement=2):
+    """Use the original source's SciPy assignment solver, loaded only on demand."""
+    try:from scipy.optimize import linear_sum_assignment
+    except ImportError:raise ContractError("Guarded-Jina-E2 requires optional scipy for source-identical assignment") from None
+    a0r=_ranks(a0,signals,pool_order=True);e2r=_ranks(e2,signals,pool_order=True)
+    top=lambda v:max(range(len(v)),key=lambda i:v[i]);at,dt,jt=top(a0),top(dense),top(jina)
+    agreed=dt==jt and dt!=at;within=agreed and a0r[dt]<=maximum_movement+1;forced=dt if within else at;huge=1e6
+    cost=[[abs(position-e2r[i]) if abs(position-a0r[i])<=maximum_movement else huge for position in range(1,len(a0)+1)] for i in range(len(a0))]
+    for i in range(len(a0)):cost[i][0]=0. if i==forced else huge
+    cost[forced]=[0.]+[huge]*(len(a0)-1);rows,cols=linear_sum_assignment(cost);ranks=[0]*len(a0)
+    for row,col in zip(rows,cols):
+        if cost[int(row)][int(col)]>=huge:raise ContractError("source bounded assignment is infeasible")
+        ranks[int(row)]=int(col)+1
+    movement=max(abs(x-y) for x,y in zip(ranks,a0r))
+    return [-float(r) for r in ranks],{'forced_top_candidate':signals[forced]['candidate_id'],'agreed_alternative':agreed,'alternative_blocked_by_movement_cap':agreed and not within,'maximum_movement':movement}
+
+
+def validate_statistical_parameters(method,parameters=None):
+    """Validate and detach method policy before any source model is invoked."""
+    if method not in METHOD_REGISTRY:raise ContractError("unknown statistical reranking method")
+    if parameters is not None and not isinstance(parameters,Mapping):raise ContractError('method parameters must be an object')
+    parameters=dict(parameters or {});allowed={'s5_minilm_weight','s5_lexical_weight','selection_digest'} if method in ('S5a','S5b','S5c') else set()
+    if set(parameters)-allowed:raise ContractError("unknown method parameter")
+    if method in ('S5a','S5b','S5c') and ('s5_minilm_weight' not in parameters or 'selection_digest' not in parameters):
+        raise ContractError("S5 requires its frozen development selection weight and digest")
+    if 'selection_digest' in parameters:
+        from .integration_contracts import require_digest
+        require_digest(parameters['selection_digest'],'selection_digest')
+    mw=finite(parameters.get('s5_minilm_weight',.55));lw=finite(parameters.get('s5_lexical_weight',.2))
+    if not 0<=mw<=1 or not 0<=lw<1:raise ContractError("S5 weights must be in range")
+    return parameters,mw,lw
+
+
+def score_signals(signals,method,*,parameters=None):
+    """Return separately typed fields in original signal order; no grading."""
+    parameters,mw,lw=validate_statistical_parameters(method,parameters)
+    alias={'S6':'Jina-60/40','S6-E1':'Jina-E1','S6-E2':'Jina-E2','S6-E3':'Jina-E3','S6-E4':'Jina-E4','S7':'Jina-RRF'}
+    named=alias.get(method,method);stat=method.startswith('S');required=[]
+    if named not in ('S1','Dense-only') and not named.startswith('Jina'):
+        required.append('minilm_logit')
+    if named.startswith('Jina') or named=='Guarded-Jina-E2':required.append('jina_logit')
+    rows=validate_signals(signals,required);dense=[r['dense_score'] for r in rows];mini=[r.get('minilm_logit',0.) for r in rows];jina=[r.get('jina_logit',0.) for r in rows];diagnostics={}
+    if named in ('S1','Dense-only'):utility=dense
+    elif named in ('A0','A0-A','A0-B'):utility=_convex(dense,mini,.45)
+    elif named=='MiniLM-only':utility=mini
+    elif named=='Jina-only':utility=jina
+    elif named in ('S2','S4','MiniLM-robust-mean','MiniLM-robust-dominance'):utility=_convex(dense,mini,.5,robust=True)
+    elif named=='S3':
+        mr=_ranks(mini,rows);utility=[1/(60+r['dense_rank'])+1/(60+rank) for r,rank in zip(rows,mr)]
+    elif named in ('S5a','S5b','S5c'):
+        if named=='S5a':lw=0.
+        d,m=robust_normalize(dense),robust_normalize(mini);lex=candidate_pool_bm25(rows) if lw or named=='S5c' else [0.]*len(rows);l=robust_normalize(lex)
+        if named=='S5c':weights,confidence=adaptive_weights(rows,mw,lw);diagnostics={'weights':weights,'confidence':confidence}
+        else:weights={'dense':(1-lw)*(1-mw),'minilm':(1-lw)*mw,'lexical':lw};diagnostics={'weights':weights}
+        utility=[weights['dense']*x+weights['minilm']*y+weights['lexical']*z for x,y,z in zip(d,m,l)]
+    elif '-W' in named or named=='Jina-60/40':
+        weight=.6 if named=='Jina-60/40' else int(named.split('-W')[1].split('/')[0])/100;utility=_convex(dense,jina if named.startswith('Jina') else mini,weight)
+    elif named in ('MiniLM-RRF','Jina-RRF'):
+        w=.6 if named.startswith('Jina') else .5;dr=_ranks(dense,rows,pool_order=True);mr=_ranks(jina if named.startswith('Jina') else mini,rows,pool_order=True);utility=[w/(60+x)+(1-w)/(60+y) for x,y in zip(dr,mr)]
+    elif named=='Jina-E1':
+        parts=[_ranks(_convex(dense,jina,w),rows,pool_order=True) for w in E2_WEIGHTS];utility=[-mean([part[i] for part in parts]) for i in range(len(rows))]
+    elif named in E2_BANDS:utility=_e2(dense,jina,rows,E2_BANDS[named])
+    elif named=='Jina-E3':
+        parts=[_ranks(_convex(dense,jina,w),rows,pool_order=True) for w in E2_WEIGHTS];dr=_ranks(dense,rows,pool_order=True);order=sorted(range(len(rows)),key=lambda i:(percentile([p[i] for p in parts]),mean([p[i] for p in parts]),dr[i],rows[i]['candidate_id']));utility=[0.]*len(rows)
+        for pos,index in enumerate(order,1):utility[index]=-float(pos)
+    elif named in ('Jina-E4','Jina-E4-no-lexical'):
+        utility=_e2(dense,jina,rows,robust=True)
+        if named=='Jina-E4':
+            bm25=[r['bm25_score'] for r in rows] if all('bm25_score' in r for r in rows) else candidate_pool_bm25(rows);br=_ranks(bm25,rows,pool_order=True);utility=[.85*x+.15/(60+y) for x,y in zip(utility,br)]
+    elif named=='Guarded-Jina-E2':
+        utility=_convex(dense,mini,.45);ar=_ranks(utility,rows,pool_order=True);order=sorted(range(len(rows)),key=lambda i:ar[i]);margin=utility[order[0]]-utility[order[1]] if len(rows)>1 else float('inf');triggered=max(range(len(rows)),key=lambda i:dense[i])!=max(range(len(rows)),key=lambda i:mini[i]) and margin<=1.4397302163247685;diagnostics={'triggered':triggered,'trigger_threshold':1.4397302163247685,'rank_movement_cap':2,'latency_scope':'no inference observed by pure score fusion'}
+        if triggered:utility,merge=bounded_merge(utility,_e2(dense,jina,rows),dense,jina,rows);diagnostics.update(merge)
+    else:raise ContractError("method lacks a verified implementation")
+    reference='statistical.ts' if stat else 'cherry.py'
+    fields={'ranking_utility':{'kind':'utility','values':utility}}
+    if named=='A0':fields['raw_model_sigmoid']={'kind':'diagnostic','values':[sigmoid(max(-60.,min(60.,v))) for v in mini]}
+    elif named=='A0-A':fields['display_utility']={'kind':'utility','values':utility}
+    else:
+        display=[max(0.,min(1.,v)) for v in dense] if named in ('S1','Dense-only') else bounded_relative(utility) if named in ('S2','S3','MiniLM-robust-mean','MiniLM-RRF') else dominance(utility,reference=reference)
+        fields['pool_relative_strength']={'kind':'pool_relative','values':display}
+    if 'minilm_logit' in required:fields['raw_minilm_logit']={'kind':'utility','values':mini}
+    if 'jina_logit' in required:fields['raw_jina_logit']={'kind':'utility','values':jina}
+    if any(not math.isfinite(v) for field in fields.values() for v in field['values']):raise ContractError("nonfinite derived score")
+    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 StatisticalScorer:
+    """A callable candidate composing pinned source scorers with the v1 I/O."""
+    def __init__(self,method,*,scorers=None,parameters=None):
+        if method not in METHOD_REGISTRY:raise ContractError("unknown statistical method")
+        checked,_,_=validate_statistical_parameters(method,parameters)
+        self.method,self.scorers,self.parameters=method,MappingProxyType(dict(scorers or {})),MappingProxyType(checked)
+        if set(self.scorers)-{'minilm','jina'}:raise ContractError("unknown source scorer")
+        self._configuration=family_configuration(method,STATISTICAL_IMPLEMENTATION_DIGEST,parameters=self.parameters,scorers=self.scorers)
+    @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']
+        if self.method!=frozen['method'] or dict(self.parameters)!=frozen['parameters']:raise ContractError("frozen family configuration changed")
+        signals=[{'candidate_id':item['candidate_id'],'dense_score':item['dense_score'],'dense_rank':item['dense_rank'],'query_text':request['query'],'passage_text':item['input']} for item in request['candidates']]
+        for name,scorer in self.scorers.items():
+            if scorer.configuration.to_dict()!=self.configuration.to_dict()['parameters']['source_scorers'][name]:raise ContractError("source scorer configuration changed")
+            response=scorer(request)
+            if response.get('query_id')!=request['query_id'] or response.get('pool_digest')!=request['pool_digest'] or response.get('schema_version')!='sphynx.rag.rerank.response.v1':raise ContractError("source scorer response identity differs")
+            scores=response.get('scores');values={item.get('candidate_id'):item.get('ranking_score') for item in scores} if isinstance(scores,list) and all(isinstance(x,dict) for x in scores) else {}
+            if len(values)!=len(signals) or len(scores)!=len(signals) or set(values)!={r['candidate_id'] for r in signals}:raise ContractError("source scorer response membership differs")
+            for signal in signals:signal[name+'_logit']=finite(values[signal['candidate_id']])
+        return score_signals(signals,self.method,parameters=self.parameters)
+    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':score} for cid,score in zip(result['candidate_ids'],result['fields']['ranking_utility']['values'])]}
+
+
+def create_statistical_scorer(method,*,scorers=None,parameters=None):return StatisticalScorer(method,scorers=scorers,parameters=parameters)
+STATISTICAL_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'))})