Divergence Strength and Quality Scoring

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

/** Independent TypeScript reference for D08-F05. Geometry is diagnostic only. */

const EPS = 1e-12;
type Row = Record<string, any>;

function finite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value); }
function requireRule(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }

export function adaptIndicator(indicator: Row): Row {
  const name = String(indicator.name ?? "").trim();
  const family = String(indicator.family ?? "").trim();
  const polarity = indicator.polarity ?? 1;
  const scale = indicator.scale;
  const pivots = indicator.pivots;
  requireRule(name, "indicator name is required"); requireRule(family, "indicator family is required");
  requireRule(polarity === -1 || polarity === 1, "indicator polarity must be -1 or 1");
  requireRule(finite(scale) && scale > 0, "indicator scale must be finite and > 0");
  requireRule(Array.isArray(pivots), "indicator pivots must be a list");
  const adapted = pivots.map((pivot: Row, index: number) => {
    requireRule(pivot && typeof pivot === "object", `indicator pivot ${index} must be an object`);
    requireRule(pivot.kind === "high" || pivot.kind === "low", `indicator pivot ${index} kind is invalid`);
    for (const field of ["event_index", "confirmation_index"]) requireRule(Number.isInteger(pivot[field]), `indicator pivot ${index} ${field} is invalid`);
    requireRule(pivot.confirmation_index >= pivot.event_index, "indicator confirmation precedes event");
    requireRule(finite(pivot.value), `indicator pivot ${index} value is invalid`);
    const prominence = pivot.prominence ?? 0.5;
    requireRule(finite(prominence) && prominence >= 0 && prominence <= 1, "indicator prominence must be in [0,1]");
    return {kind:pivot.kind,event_index:pivot.event_index,confirmation_index:pivot.confirmation_index,raw_value:pivot.value,normalized_value:polarity*pivot.value/scale,prominence};
  });
  return {name,family,polarity,scale,pivots:adapted};
}

function validatePricePivots(pivots: Row[]): void {
  requireRule(Array.isArray(pivots), "price_pivots must be a list"); const identities = new Set<string>();
  pivots.forEach((pivot,index) => {
    requireRule(pivot && typeof pivot === "object", `price pivot ${index} must be an object`);
    requireRule(pivot.kind === "high" || pivot.kind === "low", `price pivot ${index} kind is invalid`);
    for (const field of ["event_index","confirmation_index"]) requireRule(Number.isInteger(pivot[field]), `price pivot ${index} ${field} is invalid`);
    requireRule(pivot.confirmation_index >= pivot.event_index, "price confirmation precedes event");
    requireRule(finite(pivot.price) && pivot.price > 0, "price pivot price must be finite and > 0");
    const prominence = pivot.prominence ?? 0.5; requireRule(finite(prominence) && prominence >= 0 && prominence <= 1, "price prominence must be in [0,1]");
    const key=`${pivot.kind}:${pivot.event_index}`; requireRule(!identities.has(key), "same-kind price pivot event indexes must be unique"); identities.add(key);
  });
}

export function alignPivots(pricePivots: Row[], indicator: Row, maxLag=3): Row[] {
  validatePricePivots(pricePivots); requireRule(Number.isInteger(maxLag) && maxLag >= 0, "max_lag must be an integer >= 0");
  const adapted=adaptIndicator(indicator); const used=new Set<number>(); const aligned:Row[]=[];
  const ordered=[...pricePivots].sort((a,b)=>a.event_index-b.event_index || String(a.kind).localeCompare(String(b.kind)));
  for(const price of ordered){
    const candidates=adapted.pivots.map((item:Row,position:number)=>({lag:Math.abs(item.event_index-price.event_index),event:item.event_index,position,item}))
      .filter((x:Row)=>!used.has(x.position)&&x.item.kind===price.kind&&x.lag<=maxLag)
      .sort((a:Row,b:Row)=>a.lag-b.lag||a.event-b.event);
    if(!candidates.length) continue; const chosen=candidates[0]; used.add(chosen.position); const item=chosen.item;
    aligned.push({kind:price.kind,price_event_index:price.event_index,price_confirmation_index:price.confirmation_index,price:Number(price.price),price_prominence:Number(price.prominence??0.5),indicator_event_index:item.event_index,indicator_confirmation_index:item.confirmation_index,indicator_value:item.normalized_value,indicator_raw_value:item.raw_value,indicator_prominence:item.prominence,lag:chosen.lag,knowledge_index:Math.max(price.confirmation_index,item.confirmation_index),indicator:adapted.name,indicator_family:adapted.family});
  }
  return aligned;
}

function classifyPair(first:Row,second:Row,minPrice:number,minIndicator:number):string|null{
  const pd=(second.price-first.price)/Math.abs(first.price); const id=second.indicator_value-first.indicator_value;
  if(first.kind==="low"){
    if(pd<=-minPrice+EPS&&id>=minIndicator-EPS)return "regular-bullish";
    if(pd>=minPrice-EPS&&id<=-minIndicator+EPS)return "hidden-bullish";
  }else{
    if(pd>=minPrice-EPS&&id<=-minIndicator+EPS)return "regular-bearish";
    if(pd<=-minPrice+EPS&&id>=minIndicator-EPS)return "hidden-bearish";
  }
  return null;
}

export function detectDivergences(pricePivots:Row[],indicators:Row[],options:Row={}):Row[]{
  requireRule(Array.isArray(indicators)&&indicators.length>0,"indicators must be a non-empty list");
  const maxLag=options.max_lag??3,minSeparation=options.min_separation??5,maxSeparation=options.max_separation??40,minPrice=options.min_price_fraction??0.005,minIndicator=options.min_indicator_delta??0.05;
  requireRule(Number.isInteger(minSeparation)&&minSeparation>=1,"min_separation must be an integer >= 1"); requireRule(Number.isInteger(maxSeparation)&&maxSeparation>=minSeparation,"max_separation must be >= min_separation");
  requireRule(finite(minPrice)&&minPrice>=0,"min_price_fraction must be finite and >= 0"); requireRule(finite(minIndicator)&&minIndicator>=0,"min_indicator_delta must be finite and >= 0");
  const events:Row[]=[];
  for(const indicator of indicators){ const aligned=alignPivots(pricePivots,indicator,maxLag);
    for(const kind of ["low","high"]){const same=aligned.filter(x=>x.kind===kind); for(let j=0;j+1<same.length;j++){const first=same[j],second=same[j+1],span=second.price_event_index-first.price_event_index;if(span<minSeparation||span>maxSeparation)continue;const type=classifyPair(first,second,minPrice,minIndicator);if(!type)continue;const pd=(second.price-first.price)/Math.abs(first.price),id=second.indicator_value-first.indicator_value;
      events.push({type,direction:kind==="low"?"bullish":"bearish",kind,indicator:first.indicator,indicator_family:first.indicator_family,price_pair:[first.price_event_index,second.price_event_index],indicator_pair:[first.indicator_event_index,second.indicator_event_index],price_values:[first.price,second.price],indicator_values:[first.indicator_value,second.indicator_value],price_delta_fraction:pd,indicator_delta:id,separation:span,max_alignment_lag:Math.max(first.lag,second.lag),prominence:(first.price_prominence+second.price_prominence+first.indicator_prominence+second.indicator_prominence)/4,candidate_knowledge_index:Math.max(first.knowledge_index,second.knowledge_index),alignment:[first,second]});
    }}
  }
  return events.sort((a,b)=>a.candidate_knowledge_index-b.candidate_knowledge_index||String(a.type).localeCompare(String(b.type))||String(a.indicator).localeCompare(String(b.indicator)));
}

export function scoreDivergence(event:Row,maxLag=3):Row{
  requireRule(event&&typeof event==="object","event must be an object");
  const price=Math.min(Math.abs(event.price_delta_fraction)/0.04,1),indicator=Math.min(Math.abs(event.indicator_delta)/0.15,1),prominence=Math.min(Math.max(event.prominence,0),1),alignment=maxLag===0&&event.max_alignment_lag===0?1:Math.max(0,1-event.max_alignment_lag/Math.max(maxLag,1)),separation=Math.max(0,1-Math.abs(event.separation-24)/24);
  const score=Number((100*(.28*price+.28*indicator+.18*prominence+.14*alignment+.12*separation)).toFixed(6));
  const quality=score>=85?"exceptional":score>=70?"strong":score>=50?"moderate":"weak";
  const round=(x:number)=>Number(x.toFixed(6));
  return {score,quality,components:{price_geometry:round(price),indicator_geometry:round(indicator),prominence:round(prominence),alignment:round(alignment),separation:round(separation)},interpretation:"definition-strength score; not probability or expected return"};
}

export function advanceState(event:Row,bars:Row[],confirmationHorizon=12,invalidationBuffer=.005):Row{
  requireRule(Array.isArray(bars)&&bars.length>0,"bars must be a non-empty list"); requireRule(Number.isInteger(confirmationHorizon)&&confirmationHorizon>=1,"confirmation_horizon must be an integer >= 1"); requireRule(finite(invalidationBuffer)&&invalidationBuffer>=0&&invalidationBuffer<1,"invalidation_buffer must be in [0,1)");
  bars.forEach((bar,index)=>requireRule(bar&&finite(bar.close)&&finite(bar.high)&&finite(bar.low),`bar ${index} is invalid`));
  const [first,second]=event.price_pair,candidate=event.candidate_knowledge_index,direction=event.direction;
  const slice=bars.slice(first,second+1); const confirmation=direction==="bullish"?Math.max(...slice.map(x=>x.high)):Math.min(...slice.map(x=>x.low)); const invalidation=event.price_values[1]*(direction==="bullish"?1-invalidationBuffer:1+invalidationBuffer); const deadline=candidate+confirmationHorizon; const trace:Row[]=[]; let state="candidate",finalIndex:number|null=null;
  for(let index=candidate;index<Math.min(bars.length,deadline+1);index++){const bar=bars[index];if(direction==="bullish"&&bar.low<invalidation-EPS){state="invalidated";finalIndex=index}else if(direction==="bearish"&&bar.high>invalidation+EPS){state="invalidated";finalIndex=index}else if(direction==="bullish"&&bar.close>confirmation+EPS){state="confirmed";finalIndex=index}else if(direction==="bearish"&&bar.close<confirmation-EPS){state="confirmed";finalIndex=index}trace.push({index,state,close:bar.close});if(finalIndex!==null)break;}
  if(finalIndex===null&&bars.length-1>=deadline){state="expired";finalIndex=deadline;if(trace.length)trace[trace.length-1].state="expired"}
  return {state,candidate_index:candidate,final_index:finalIndex,confirmation_level:Number(confirmation.toFixed(6)),invalidation_level:Number(invalidation.toFixed(6)),deadline,trace};
}

export function combineConfluence(events:Row[],weights:Record<string,number>,minimumIndicators=2):Row[]{
  requireRule(Array.isArray(events),"events must be a list");requireRule(weights&&Object.keys(weights).length>0,"weights must be a non-empty object");requireRule(Number.isInteger(minimumIndicators)&&minimumIndicators>=1,"minimum_indicators must be >= 1");const total=Object.values(weights).reduce((a,b)=>a+b,0);requireRule(total>0&&Object.values(weights).every(x=>finite(x)&&x>=0),"weights must be finite, non-negative, and sum > 0");
  const groups=new Map<string,Row[]>();for(const event of events){const key=`${event.type}|${event.price_pair.join(",")}`;groups.set(key,[...(groups.get(key)??[]),event]);}const out:Row[]=[];
  for(const group of groups.values()){const unique=new Map(group.map(x=>[x.indicator,x]));if(unique.size<minimumIndicators)continue;const selected=[...unique.values()],selectedWeight=selected.reduce((sum,x)=>sum+(weights[x.indicator]??0),0);if(selectedWeight<=0)continue;const quality=selected.reduce((sum,x)=>sum+(weights[x.indicator]??0)*scoreDivergence(x).score,0)/selectedWeight,coverage=selectedWeight/total,families=new Set(selected.map(x=>x.indicator_family)).size/selected.length,score=Number((.45*quality+35*coverage+20*families).toFixed(6));out.push({type:selected[0].type,direction:selected[0].direction,price_pair:selected[0].price_pair,indicators:[...unique.keys()].sort(),indicator_count:unique.size,weighted_quality:Number(quality.toFixed(6)),weight_coverage:Number(coverage.toFixed(6)),family_coverage:Number(families.toFixed(6)),confluence_score:score,knowledge_index:Math.max(...selected.map(x=>x.candidate_knowledge_index)),interpretation:"agreement score; not independent evidence or probability"});}
  return out.sort((a,b)=>b.confluence_score-a.confluence_score||String(a.type).localeCompare(String(b.type))||String(a.price_pair).localeCompare(String(b.price_pair)));
}

export function rankUniverse(records:Row[],asOfIndex:number):Row[]{
  requireRule(Array.isArray(records),"records must be a list");requireRule(Number.isInteger(asOfIndex)&&asOfIndex>=0,"as_of_index must be an integer >= 0");const ranked:Row[]=[];
  for(const record of records){if((record.available_index??0)>asOfIndex||record.eligible===false)continue;for(const field of ["confluence_score","freshness","liquidity","data_quality"])requireRule(finite(record[field])&&record[field]>=0&&record[field]<=100,`${field} must be in [0,100]`);requireRule(record.state==="candidate"||record.state==="confirmed","scanner state must be candidate or confirmed");const state=record.state==="confirmed"?100:70;const rank=Number((.55*record.confluence_score+.15*state+.1*record.freshness+.1*record.liquidity+.1*record.data_quality).toFixed(6));ranked.push({symbol:String(record.symbol),state:record.state,divergence_type:record.divergence_type,rank_score:rank,components:{confluence_score:record.confluence_score,freshness:record.freshness,liquidity:record.liquidity,data_quality:record.data_quality},as_of_index:asOfIndex,interpretation:"deterministic triage priority; not an order or return forecast"});}
  ranked.sort((a,b)=>b.rank_score-a.rank_score||a.symbol.localeCompare(b.symbol));ranked.forEach((x,i)=>x.rank=i+1);return ranked;
}

export function runTopic(payload:Row,topicId?:string):Row{
  const selected=topicId??String(payload.topic_id??""),p=payload.parameters??{},price=payload.price_pivots??[],indicators=payload.indicators??[],maxLag=p.max_lag??3;
  if(selected.endsWith("A01")){if(!indicators.length)return{topic_id:selected,state:"warmup",alignments:[],reason:"no-indicator-pivots"};const alignments=alignPivots(price,indicators[0],maxLag);return{topic_id:selected,state:alignments.length>=2?"ready":"warmup",alignments,alignment_count:alignments.length,reason:alignments.length>=2?"aligned":"fewer-than-two-alignments"};}
  if(selected.endsWith("A04")){const adapters=indicators.map(adaptIndicator);return{topic_id:selected,state:adapters.length?"ready":"warmup",adapters,adapter_count:adapters.length};}
  const events=indicators.length?detectDivergences(price,indicators,p):[];
  if(selected.endsWith("A02")){const filtered=events.filter(x=>x.type.startsWith("regular-"));return{topic_id:selected,state:filtered.length?"detected":"not-detected",events:filtered,event_count:filtered.length};}
  if(selected.endsWith("A03")){const filtered=events.filter(x=>x.type.startsWith("hidden-"));return{topic_id:selected,state:filtered.length?"detected":"not-detected",events:filtered,event_count:filtered.length};}
  if(selected.endsWith("A05")){if(!events.length)return{topic_id:selected,state:"not-detected",score:null,reason:"no-divergence-event"};return{topic_id:selected,state:"scored",event:events[0],score:scoreDivergence(events[0],maxLag)};}
  if(selected.endsWith("A06")){if(!events.length)return{topic_id:selected,state:"searching",event:null,lifecycle:null};const event=events[0],lifecycle=advanceState(event,payload.bars??[],p.confirmation_horizon??12,p.invalidation_buffer??.005);return{topic_id:selected,state:lifecycle.state,event,lifecycle};}
  if(selected.endsWith("A07")){const groups=combineConfluence(events,payload.weights??{},p.minimum_indicators??2);return{topic_id:selected,state:groups.length?"confluent":"insufficient-confluence",groups,group_count:groups.length};}
  if(selected.endsWith("A08")){const ranking=rankUniverse(payload.universe??[],payload.as_of_index??((payload.bars??[]).length-1));return{topic_id:selected,state:ranking.length?"ranked":"empty",ranking,eligible_count:ranking.length};}
  throw new Error(`unsupported topic id: ${selected}`);
}