"""M2 v1.2 scorer for review. Importing this module never reads project data. No learning model is trained. Real panel execution requires a separate approval. """ from dataclasses import dataclass import hashlib import numpy as np from scipy.spatial import cKDTree from evaluate_s1_shortfall import decision as shortfall_decision PERMUTATION_SEEDS=tuple(range(2026111401,2026111406)) QUERY_BOOTSTRAP_SEED=2026111406 SOURCE_BOOTSTRAP_SEED=2026111407 ARMS=('A','A+S','B','B+edge_shuffle','C','B+stratified_edge_shuffle') DIMENSIONS={'A':2,'A+S':6,'B':6,'B+edge_shuffle':10,'C':10,'B+stratified_edge_shuffle':10} CONTRASTS={'B-(A+S)':('B','A+S','primary'), 'C-(B+edge_shuffle)':('C','B+edge_shuffle','primary'), 'C-(B+stratified_edge_shuffle)':('C','B+stratified_edge_shuffle','secondary'), 'B-A':('B','A','descriptive'),'C-B':('C','B','descriptive')} AUDIT_TOLERANCE=1e-10 def digest(a): a=np.asarray(a) return hashlib.sha256(a.dtype.str.encode()+str(a.shape).encode()+a.tobytes()).hexdigest() @dataclass class Part: case: str source: str prefix: int ids: np.ndarray features: np.ndarray # d/t, gate/Rg, g12,g23,gate q1,q2,edge mean/max q1/q2 counts: np.ndarray eligible: np.ndarray near: np.ndarray draw_to_unique: np.ndarray positive_mass_fraction: float=1. provenance: str='synthetic' def validate(self): u=len(self.ids) if self.features.shape!=(u,10):raise ValueError('Expected all ten true columns') if len(set(map(int,self.ids)))!=u or np.any(np.diff(self.ids)<=0):raise ValueError('IDs must be distinct and sorted') if any(np.asarray(x).shape!=(u,) for x in [self.counts,self.eligible,self.near]):raise ValueError('Shape mismatch') if self.eligible.dtype!=bool or self.near.dtype!=bool:raise ValueError('Explicit boolean masks required') if not np.issubdtype(self.counts.dtype,np.integer) or np.any(self.counts<=0):raise ValueError('Positive integer multiplicities required') inv=np.asarray(self.draw_to_unique) if inv.ndim!=1 or not np.issubdtype(inv.dtype,np.integer) or not len(inv):raise ValueError('Ordered draw slots required') if inv.min()<0 or inv.max()>=u or not np.array_equal(np.bincount(inv,minlength=u),self.counts):raise ValueError('Draw counts disagree') if not np.isfinite(self.features[self.eligible]).all():raise ValueError('Nonfinite eligible descriptor') if not 0<=self.positive_mass_fraction<=1:raise ValueError('Invalid positive-distance mass share') def rank_weights(parts): """Each training part has total 1/P; within part cE/K, no second mass.""" if not parts:raise ValueError('No training parts') weights=[] for part in parts: part.validate();c=part.counts[part.eligible] if not len(c) or c.sum()==0:raise ValueError('Zero eligible training part; cannot silently drop it') weights.append(c.astype(np.float64)/int(c.sum())/len(parts)) return weights @dataclass class RankMap: values: np.ndarray cumulative: np.ndarray @classmethod def fit(cls,values,weights): values=np.asarray(values,dtype=np.float64);weights=np.asarray(weights,dtype=np.float64) if values.ndim!=1 or values.shape!=weights.shape or not len(values):raise ValueError('Rank input shape') if not np.isfinite(values).all() or not np.isfinite(weights).all() or np.any(weights<=0):raise ValueError('Invalid rank input') order=np.argsort(values,kind='stable');v=values[order];w=weights[order] starts=np.r_[0,np.flatnonzero(v[1:]!=v[:-1])+1] total=np.add.reduceat(w,starts);cdf=np.r_[0.,np.cumsum(total)] cdf/=cdf[-1];cdf[-1]=1. return cls(v[starts],cdf) def transform(self,x): x=np.asarray(x,dtype=np.float64) if not np.isfinite(x).all():raise ValueError('Nonfinite transform input') lo=np.searchsorted(self.values,x,side='left');hi=np.searchsorted(self.values,x,side='right') return (self.cumulative[lo]+self.cumulative[hi])/2 def audit(self,x,counts): x=np.asarray(x);counts=np.asarray(counts);den=int(counts.sum()) low=xself.values[-1] return dict(constant=len(self.values)==1,training_min=float(self.values[0]),training_max=float(self.values[-1]), below_slots=int(counts[low].sum()),above_slots=int(counts[high].sum()),denominator_slots=den, below_fraction=float(counts[low].sum()/den) if den else None, above_fraction=float(counts[high].sum()/den) if den else None, query_raw_min=float(x.min()) if len(x) else None,query_raw_max=float(x.max()) if len(x) else None) def fit_maps(parts): weights=rank_weights(parts);x=np.concatenate([p.features[p.eligible] for p in parts]);w=np.concatenate(weights) return [RankMap.fit(x[:,j],w) for j in range(10)],weights def apply_maps(x,maps): return np.column_stack([m.transform(x[:,j]) for j,m in enumerate(maps[:x.shape[1]])]) def D_p(x,y): x=np.asarray(x,dtype=np.float64);y=np.asarray(y,dtype=np.float64) if x.shape[-1]!=y.shape[-1] or x.shape[-1]<1:raise ValueError('Descriptor dimensions differ') return np.sqrt(np.mean((x-y)**2,axis=-1)) def knn_mean(reference,query,physical_ids,k=8): """Exact tree search, then direct RMS distances and stable physical-ID ties. Radius padding only protects candidate retrieval from floating rounding; it neither changes distances nor turns nearby distances into ties. """ reference=np.asarray(reference,dtype=np.float64);query=np.asarray(query,dtype=np.float64) keys=[tuple(key) for key in physical_ids] if len(keys)!=len(reference) or len(set(keys))!=len(keys):raise ValueError('Duplicate physical reference node') if reference.ndim!=2 or query.ndim!=2 or reference.shape[1]!=query.shape[1]:raise ValueError('kNN shape') if not np.isfinite(reference).all() or not np.isfinite(query).all():raise ValueError('Nonfinite kNN input') if len(reference)0)==mode).all(1));small=len(ids)<8 if not small:stratified[ids]=ids[rng.permutation(len(ids))] strata.append(dict(mode=list(map(int,mode)),size=len(ids),unchanged_small_stratum=small)) return ordinary,stratified,strata def edge_audit(edges,gaps): edges=np.asarray(edges);gaps=np.asarray(gaps);n=len(edges) if not np.isfinite(edges).all() or not np.isfinite(gaps).all():raise ValueError('Nonfinite shuffle result; no repair') violations=np.column_stack([-edges[:,0],edges[:,0]-edges[:,1],edges[:,1]-gaps[:,0], -edges[:,2],edges[:,2]-edges[:,3],edges[:,3]-gaps[:,1]]) both=(gaps>0).all(1);order=np.empty((0,2)) if both.any():order=edges[both,:2]/gaps[both,0,None]-edges[both,2:]/gaps[both,1,None] return dict(nodes=n,raw_bound_violation_count=int((violations>0).any(1).sum()), tolerant_bound_violation_count=int((violations>AUDIT_TOLERANCE).any(1).sum()), maximum_raw_bound_excess=float(np.maximum(violations,0).max(initial=0)), both_positive_nodes=int(both.sum()),raw_cross_channel_order_violations=int((order>0).any(1).sum()), tolerant_cross_channel_order_violations=int((order>AUDIT_TOLERANCE).any(1).sum()), maximum_cross_channel_order_excess=float(np.maximum(order,0).max(initial=0)),tolerance=AUDIT_TOLERANCE) def shuffled_blocks(x,prefix,seed): """x contains eligible distinct true nodes in ascending node-ID order.""" gaps=x[:,2:4];edges=x[:,6:10];plain,strat,strata=permutation_maps(prefix,seed,gaps) node=x.copy();node[:,2:6]=x[plain,2:6] edge=x.copy();edge[:,6:10]=edges[plain] normal=x.copy();active=np.zeros(len(x),bool) for row in strata: if not row['unchanged_small_stratum']:active|=((gaps>0)==np.array(row['mode'],bool)).all(1) normalized=np.zeros_like(edges) for ch in range(2): mask=gaps[:,ch]>0;normalized[mask,2*ch:2*ch+2]=edges[mask,2*ch:2*ch+2]/gaps[mask,ch,None] normal[active,6+2*ch:8+2*ch]=normalized[strat[active],2*ch:2*ch+2]*gaps[active,ch,None] modes=lambda g:{str(tuple(map(int,m))):int(((g>0)==m).all(1).sum()) for m in [(0,0),(0,1),(1,0),(1,1)]} audit=dict(seed=seed,prefix=prefix,ordinary_index_sha256=digest(plain),stratified_index_sha256=digest(strat), ordinary_slot_changes=int((plain!=np.arange(len(x))).sum()),stratified_slot_changes=int((strat!=np.arange(len(x))).sum()), ordinary_block_value_changes=int((edge[:,6:10]!=edges).any(1).sum()), stratified_block_value_changes=int((normal[:,6:10]!=edges).any(1).sum()), node_block_value_changes=int((node[:,2:6]!=x[:,2:6]).any(1).sum()),denominator_slots=len(x), recipient_zero_modes=modes(gaps),ordinary_donor_zero_modes=modes(gaps[plain]),stratified_donor_zero_modes=modes(gaps[strat]),strata=strata, ordinary=edge_audit(edge[:,6:10],gaps),stratified=edge_audit(normal[:,6:10],gaps)) return node,edge,normal,audit def query_bootstrap_counts(part,replicates=200): part.validate();n=len(part.draw_to_unique) rng=np.random.Generator(np.random.PCG64(np.random.SeedSequence([QUERY_BOOTSTRAP_SEED,int(part.prefix)]))) result=np.empty((replicates,len(part.ids)),np.int64) for b in range(replicates): slots=rng.integers(0,n,size=n,dtype=np.int64) result[b]=np.bincount(part.draw_to_unique[slots],minlength=len(part.ids)) return result def source_bootstrap_indices(source_keys,replicates=2000): keys=tuple(sorted(source_keys)) if len(set(keys))!=len(keys) or not keys:raise ValueError('Source identities must be unique') rng=np.random.Generator(np.random.PCG64(np.random.SeedSequence([SOURCE_BOOTSTRAP_SEED]))) return keys,np.stack([rng.integers(0,len(keys),size=len(keys),dtype=np.int64) for _ in range(replicates)]) def ratio(scores,counts,mask): scores=np.asarray(scores);counts=np.asarray(counts);mask=np.asarray(mask,bool) accepted=mask&(counts>0);den=int(counts[accepted].sum()) if den==0:return np.nan if not np.isfinite(scores[accepted]).all():return np.nan return float(np.dot(counts[accepted],scores[accepted])/den) def slice_estimates(part,scores,bootstrap): """Returns point and query replicates; never zero-multiplies missing values.""" out={} for name,mask in [('whole',part.eligible),('near',part.eligible&part.near)]: point=ratio(scores,part.counts,mask) reps=np.array([ratio(scores,c,mask) for c in bootstrap]) accepted=int(part.counts[mask].sum());n=int(part.counts.sum()) out[name]=dict(point=point,replicates=reps,accepted_draws=accepted, point_reason='zero_denominator' if not accepted else ('missing_node_score' if not np.isfinite(point) else None), query_level=interval(point,reps), conditional_positive_mass_share=accepted/n,full_mass_share=part.positive_mass_fraction*accepted/n, positive_mass_fraction=part.positive_mass_fraction,boundary_unscored_mass_share=1-part.positive_mass_fraction) out['near_fraction_of_eligible']=out['near']['accepted_draws']/out['whole']['accepted_draws'] if out['whole']['accepted_draws'] else np.nan return out def interval(point,replicates): a=np.asarray(replicates,dtype=np.float64);good=a[np.isfinite(a)];n=len(good) if not np.isfinite(point):return dict(point=None,valid_replicates=n,total_replicates=len(a),SE=None,interval95=None,reason='point_NA') if n<2:return dict(point=float(point),valid_replicates=n,total_replicates=len(a),SE=None,interval95=None,reason='fewer_than_2_valid_replicates') return dict(point=float(point),valid_replicates=n,total_replicates=len(a),SE=float(np.std(good,ddof=1)), interval95=np.quantile(good,[.025,.975],method='linear').tolist(),reason=None) def aggregate_parts(values,source_keys): """Fixed parts/sources: a missing necessary part makes its aggregate NA.""" a=np.asarray(values,dtype=np.float64) if len(a)!=len(source_keys) or not len(a):raise ValueError('Aggregation identities') sources=tuple(sorted(set(source_keys)));by_source=np.stack([a[np.array(source_keys)==s].mean(axis=0) for s in sources]) return dict(source_keys=sources,source_values=by_source,source_equal=by_source.mean(axis=0),part_equal=a.mean(axis=0)) def ranking(source_interval,category): if category=='descriptive':return 'descriptive_only' ci=source_interval['interval95'] if ci is None:return 'NA' if ci[1]<0:return 'ranks_ahead' if category=='primary' else 'secondary_ahead' if ci[0]>0:return 'ranks_behind' if category=='primary' else 'secondary_behind' return 'no_ranking_difference' def contrast_report(points,query_replicates,source_keys,source_indices,category): """Inputs already are paired differences, not separate unpaired intervals.""" aggregate=aggregate_parts(points,source_keys);query=aggregate_parts(query_replicates,source_keys) source_values=aggregate['source_values'] source_reps=source_values[source_indices].mean(axis=1) source_ci=interval(aggregate['source_equal'],source_reps) return dict(category=category,source_equal_point=float(aggregate['source_equal']), part_equal_point=float(aggregate['part_equal']),source_level=source_ci, query_level=interval(aggregate['source_equal'],query['source_equal']), part_equal_query_level=interval(aggregate['part_equal'],query['part_equal']), decision=ranking(source_ci,category),source_keys=aggregate['source_keys'], source_bootstrap_scope='Resamples fixed LOPO source statistics (paired differences for contrasts); does not refit folds/ranks or resample training pools.', query_bootstrap_scope='Draw-slot error only, conditional on panel, reference pools, ranks, permutations and node scores.') def score_fold(training,test,allow_small_synthetic=False): training=sorted(training,key=lambda p:(p.source,p.case));test.validate() if test.source in {p.source for p in training}:raise ValueError('Source leakage') if len({p.case for p in training})!=len(training) or len({p.source for p in training})!=len(training):raise ValueError('One representative per source required') for p in training:p.validate() if allow_small_synthetic and any(p.provenance!='synthetic' for p in [*training,test]):raise ValueError('Cannot bypass shortfall for real data') gate=shortfall_decision([int(p.eligible.sum()) for p in training]) if not gate['comparable'] and not allow_small_synthetic:return dict(status='shortfall',gate=gate) if any(not p.eligible.any() for p in training):return dict(status='zero_eligible_training_part',gate=gate) maps,weights=fit_maps(training) true=[p.features[p.eligible] for p in training];keys=[(p.source,p.case,int(i)) for p in training for i in p.ids[p.eligible]] qraw=test.features[test.eligible];truth=np.concatenate(true) scores={arm:np.full((5,len(test.ids)),np.nan) for arm in ARMS};nearest={};audits={};reference_clipping={};searches=0;tie_searches=0 def evaluate(arm,raw,seed_index): nonlocal searches,tie_searches dim=DIMENSIONS[arm];ref=apply_maps(raw[:,:dim],maps);query=apply_maps(qraw[:,:dim],maps) result=knn_mean(ref,query,keys) if result['status']=='PASS': neighbor_sources=np.array([key[0] for key in keys])[result['indices']] result['zero_distance_neighbors']=(result['distances']==0).sum(axis=1) result['distinct_neighbor_sources']=np.array([len(set(row)) for row in neighbor_sources]) result['largest_source_neighbor_fraction']=np.array([max(np.unique(row,return_counts=True)[1])/8 for row in neighbor_sources]) scores[arm][seed_index,test.eligible]=result['scores'];nearest[(arm,seed_index)]=result searches+=result.get('logical_knn_queries',0);tie_searches+=result.get('tie_radius_queries',0) for arm in ['A','B','C']: evaluate(arm,truth,0);scores[arm][1:]=scores[arm][0] for si,seed in enumerate(PERMUTATION_SEEDS): blocks=[shuffled_blocks(x,p.prefix,seed) for x,p in zip(true,training)] for j,arm in enumerate(['A+S','B+edge_shuffle','B+stratified_edge_shuffle']): raw=np.concatenate([b[j] for b in blocks]);evaluate(arm,raw,si) reference_clipping[(arm,si)]={p.case:[m.audit(b[j][:,col],p.counts[p.eligible]) for col,m in enumerate(maps)] for p,b in zip(training,blocks)} audits[str(seed)]={p.case:b[3] for p,b in zip(training,blocks)} clipping={} for name,mask in [('whole',test.eligible),('near',test.eligible&test.near)]: clipping[name]=[m.audit(test.features[mask,j],test.counts[mask]) for j,m in enumerate(maps)] boot=query_bootstrap_counts(test);estimates={} for arm in ARMS:estimates[arm]=[slice_estimates(test,s,boot) for s in scores[arm]] return dict(status='PASS' if len(keys)>=8 else 'fewer_than_8_references',gate=gate,scores=scores, estimates=estimates,rank_maps=maps,rank_weights=weights,physical_reference_ids=keys, nearest=nearest,shuffle_audits=audits,query_clipping=clipping,control_reference_clipping=reference_clipping, query_bootstrap_counts_sha256=digest(boot),logical_knn_queries=searches,tie_radius_queries=tie_searches) def summarize_folds(parts,fold_results): if len(parts)!=len(fold_results):raise ValueError('Missing fold') if any(r['status'] not in ['PASS','fewer_than_8_references'] for r in fold_results):raise ValueError('Unscored fold retained; no aggregate') sources=[p.source for p in parts];source_order,source_indices=source_bootstrap_indices(set(sources));report={} for name,(left,right,category) in CONTRASTS.items(): report[name]={} for slice_name in ['whole','near']: point=np.array([[r['estimates'][left][s][slice_name]['point']-r['estimates'][right][s][slice_name]['point'] for s in range(5)] for r in fold_results]) reps=np.array([[r['estimates'][left][s][slice_name]['replicates']-r['estimates'][right][s][slice_name]['replicates'] for s in range(5)] for r in fold_results]) each=[contrast_report(point[:,s],reps[:,s],sources,source_indices,category) for s in range(5)] report[name][slice_name]=dict(per_seed=dict(zip(map(str,PERMUTATION_SEEDS),each)), five_seed_mean=contrast_report(point.mean(axis=1),reps.mean(axis=1),sources,source_indices,category)) arm_report={} for arm in ARMS: arm_report[arm]={} for slice_name in ['whole','near']: point=np.array([[r['estimates'][arm][s][slice_name]['point'] for s in range(5)] for r in fold_results]) reps=np.array([[r['estimates'][arm][s][slice_name]['replicates'] for s in range(5)] for r in fold_results]) arm_report[arm][slice_name]=dict(per_seed={str(seed):contrast_report(point[:,s],reps[:,s],sources,source_indices,'descriptive') for s,seed in enumerate(PERMUTATION_SEEDS)}, five_seed_mean=contrast_report(point.mean(axis=1),reps.mean(axis=1),sources,source_indices,'descriptive')) return dict(arms=arm_report,contrasts=report,source_order=source_order,source_bootstrap_indices_sha256=digest(source_indices), source_bootstrap_seed=SOURCE_BOOTSTRAP_SEED,source_bootstrap_replicates=2000, query_bootstrap_seed=QUERY_BOOTSTRAP_SEED,query_bootstrap_replicates=200, decision_uses='Paired absolute M2 differences; source-level percentile interval only; no effect-size margin.', warning='Cross-dimension B-A and C-B are descriptive. Secondary normalized shuffle is not a gate.')