Unified Candlestick Pattern Registry

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

/** Topic entry point for Unified Candlestick Pattern Registry. */
/** Reference algorithms for D06-F05. These are explicit teaching conventions,
 * not TA-Lib parity and not estimates of trading profitability. */

type AnyMap = Record<string, any>;
const PATTERN_ID = /^D06-F0[2-4]-A\d{2}$/;
const DIRECTIONS = new Set(["bullish", "bearish", "neutral"]);
const FEATURE_WEIGHTS: AnyMap = {geometry:.30,support_resistance:.20,trend:.15,volatility:.10,volume:.10,confirmation:.15};

function object(value:any,name:string):AnyMap { if(!value||typeof value!=="object"||Array.isArray(value))throw new TypeError(`${name} must be an object`);return value; }
function array(value:any,name:string):any[] { if(!Array.isArray(value))throw new TypeError(`${name} must be an array`);return value; }
function text(value:any,name:string):string { if(typeof value!=="string"||!value.trim())throw new TypeError(`${name} must be a non-empty string`);return value.trim(); }
function number(value:any,name:string):number { if(typeof value!=="number"||!Number.isFinite(value))throw new TypeError(`${name} must be a finite number`);return value; }
function integer(value:any,name:string,minimum?:number):number { if(!Number.isInteger(value))throw new TypeError(`${name} must be an integer`);if(minimum!==undefined&&value<minimum)throw new RangeError(`${name} must be at least ${minimum}`);return value; }
function unit(value:any,name:string):number { const n=number(value,name);if(n<0||n>1)throw new RangeError(`${name} must be in [0, 1]`);return n; }
function positive(value:any,name:string):number { const n=number(value,name);if(n<=0)throw new RangeError(`${name} must be positive`);return n; }
function direction(value:any,name="direction"):string { const d=text(value,name);if(!DIRECTIONS.has(d))throw new RangeError(`${name} must be bullish, bearish, or neutral`);return d; }
function clamp(value:number):number{return Math.max(0,Math.min(1,value));}
function median(values:number[]):number { const ordered=[...values].sort((a,b)=>a-b),n=ordered.length;return n%2?ordered[(n-1)/2]:(ordered[n/2-1]+ordered[n/2])/2; }

export function buildRegistry(data:AnyMap):AnyMap {
  const source=object(data,"data"),specs=array(source.patterns,"patterns"),ids=new Set<string>(),names=new Set<string>();
  const patterns=specs.map((raw,index)=>{const spec=object(raw,`patterns[${index}]`),patternId=text(spec.pattern_id,`patterns[${index}].pattern_id`),name=text(spec.name,`patterns[${index}].name`),folded=name.toLocaleLowerCase();
    if(!PATTERN_ID.test(patternId))throw new RangeError(`patterns[${index}].pattern_id is outside D06-F02 through D06-F04`);
    if(ids.has(patternId)||names.has(folded))throw new RangeError("pattern IDs and names must be unique");ids.add(patternId);names.add(folded);
    const window=integer(spec.window,`patterns[${index}].window`,1);if(window>5)throw new RangeError("pattern windows above five bars are outside this registry");
    const enabled=spec.enabled??true;if(typeof enabled!=="boolean")throw new TypeError(`patterns[${index}].enabled must be boolean`);
    return {pattern_id:patternId,name,direction:direction(spec.direction,`patterns[${index}].direction`),window,detector:text(spec.detector,`patterns[${index}].detector`),version:text(spec.version,`patterns[${index}].version`),enabled,priority:integer(spec.priority??0,`patterns[${index}].priority`,0)};
  }).sort((a,b)=>a.pattern_id.localeCompare(b.pattern_id));
  return {state:"ready",registry_id:patterns.map(p=>`${p.pattern_id}@${p.version}`).join(";"),pattern_count:patterns.length,enabled_count:patterns.filter(p=>p.enabled).length,max_window:patterns.length?Math.max(...patterns.map(p=>p.window)):0,patterns};
}

function makeOccurrence(data:AnyMap):AnyMap {
  const s=object(data,"data"),instrument=text(s.instrument_id,"instrument_id"),interval=text(s.interval,"interval"),patternId=text(s.pattern_id,"pattern_id");
  if(!PATTERN_ID.test(patternId))throw new RangeError("pattern_id is outside D06-F02 through D06-F04");
  const start=integer(s.start_index,"start_index",0),end=integer(s.end_index,"end_index",0);if(end<start)throw new RangeError("end_index cannot precede start_index");
  if(typeof s.bar_closed!=="boolean")throw new TypeError("bar_closed must be boolean");if(!s.bar_closed)throw new RangeError("canonical occurrences require a closed terminal bar");
  const detectedAt=text(s.detected_at,"detected_at"),availableAt=text(s.available_at,"available_at"),endTime=text(s.end_time,"end_time"),version=text(s.detector_version,"detector_version");
  return {occurrence_id:`${instrument}|${interval}|${endTime}|${patternId}|${start}:${end}|${version}`,instrument_id:instrument,interval,price_basis:text(s.price_basis,"price_basis"),session:text(s.session,"session"),pattern_id:patternId,pattern_name:text(s.pattern_name,"pattern_name"),direction:direction(s.direction),start_index:start,end_index:end,start_time:text(s.start_time,"start_time"),end_time:endTime,detected_at:detectedAt,available_at:availableAt,bar_closed:true,detector_version:version,geometry_score:unit(s.geometry_score,"geometry_score"),reason_codes:array(s.reason_codes??[],"reason_codes").map((v,i)=>text(v,`reason_codes[${i}]`))};
}

function scanMarket(data:AnyMap):AnyMap {
  const s=object(data,"data"),asOf=text(s.as_of,"as_of"),minimum=unit(s.minimum_geometry_score??0,"minimum_geometry_score"),registry=buildRegistry({patterns:s.registry}),enabled=new Map<string,AnyMap>(registry.patterns.filter((p:AnyMap)=>p.enabled).map((p:AnyMap)=>[p.pattern_id,p]));
  const occurrences:AnyMap[]=[],skipped:AnyMap[]=[],candidates=array(s.candidates,"candidates");
  candidates.forEach((raw,index)=>{const c=object(raw,`candidates[${index}]`),spec=enabled.get(c.pattern_id);if(!spec){skipped.push({candidate:String(index),reason:"disabled-or-unregistered"});return;}if(c.bar_closed!==true){skipped.push({candidate:String(index),reason:"provisional-terminal-bar"});return;}if(text(c.available_at,`candidates[${index}].available_at`)>asOf){skipped.push({candidate:String(index),reason:"future-at-scan-time"});return;}if(unit(c.geometry_score,`candidates[${index}].geometry_score`)<minimum){skipped.push({candidate:String(index),reason:"below-geometry-threshold"});return;}occurrences.push(makeOccurrence({...c,pattern_name:c.pattern_name??spec.name,detector_version:c.detector_version??spec.version,reason_codes:c.reason_codes??["geometry-matched"]}));});
  occurrences.sort((a,b)=>[a.instrument_id,a.interval,a.end_time,a.pattern_id].join("|").localeCompare([b.instrument_id,b.interval,b.end_time,b.pattern_id].join("|")));
  return {state:"ready",as_of:asOf,candidate_count:candidates.length,occurrence_count:occurrences.length,skipped_count:skipped.length,occurrences,skipped};
}

function scoreContext(data:AnyMap):AnyMap {
  const s=object(data,"data"),features=object(s.features,"features"),weights=object(s.weights??FEATURE_WEIGHTS,"weights"),normalized:AnyMap={};
  for(const [name,raw] of Object.entries(weights)){if(!(name in FEATURE_WEIGHTS))throw new RangeError(`unsupported context feature ${name}`);const w=number(raw,`weights.${name}`);if(w<0)throw new RangeError("weights must be non-negative");normalized[name]=w;}
  const total=Object.values(normalized).reduce((sum:any,v:any)=>sum+v,0) as number;if(total<=0)throw new RangeError("at least one context weight must be positive");let available=0,weighted=0;const contributions:AnyMap={};
  for(const [name,w] of Object.entries(normalized) as [string,number][]){const raw=features[name];if(raw===null||raw===undefined){contributions[name]=null;continue;}const v=unit(raw,`features.${name}`);available+=w;weighted+=w*v;contributions[name]=w*v;}
  const coverage=available/total,minimum=unit(s.minimum_coverage??.70,"minimum_coverage"),ready=available>0&&coverage>=minimum;
  return {state:ready?"ready":"insufficient-evidence",score:ready?100*weighted/available:null,evidence_coverage:coverage,minimum_coverage:minimum,contributions,interpretation:"context-fit-index-not-probability"};
}

function supportResistanceContext(data:AnyMap):AnyMap {
  const s=object(data,"data"),price=number(s.pattern_price,"pattern_price"),atr=positive(s.atr,"atr"),d=direction(s.direction);if(d==="neutral")return {state:"unsupported-direction",context_score:null,matched_level:null};
  const occurrenceIndex=integer(s.occurrence_index,"occurrence_index",0),maximum=positive(s.max_distance_atr??2,"max_distance_atr"),target=d==="bullish"?"support":"resistance",eligible:any[]=[];
  array(s.levels,"levels").forEach((raw,index)=>{const level=object(raw,`levels[${index}]`),kind=text(level.kind,`levels[${index}].kind`);if(!["support","resistance"].includes(kind))throw new RangeError("level kind must be support or resistance");const confirmed=integer(level.confirmed_index,`levels[${index}].confirmed_index`,0),levelPrice=number(level.price,`levels[${index}].price`),strength=unit(level.strength,`levels[${index}].strength`);if(kind===target&&confirmed<=occurrenceIndex)eligible.push({distance:Math.abs(price-levelPrice)/atr,level:{price:levelPrice,kind,strength,confirmed_index:confirmed}});});
  if(!eligible.length)return {state:"no-causal-level",context_score:null,matched_level:null,target_kind:target};eligible.sort((a,b)=>a.distance-b.distance||b.level.strength-a.level.strength||a.level.price-b.level.price);const best=eligible[0];
  return {state:"ready",target_kind:target,distance_atr:best.distance,context_score:clamp(1-best.distance/maximum),matched_level:best.level};
}

function trendVolatilityVolumeContext(data:AnyMap):AnyMap {
  const s=object(data,"data"),closes=array(s.prior_closes,"prior_closes").map((v,i)=>number(v,`prior_closes[${i}]`)),ranges=array(s.prior_ranges,"prior_ranges").map((v,i)=>number(v,`prior_ranges[${i}]`)),volumes=array(s.prior_volumes,"prior_volumes").map((v,i)=>number(v,`prior_volumes[${i}]`)),lookback=integer(s.lookback,"lookback",3),count=Math.min(closes.length,ranges.length,volumes.length);
  if(count<lookback)return {state:"warmup",history_count:count};const cs=closes.slice(-lookback),rs=ranges.slice(-lookback),vs=volumes.slice(-lookback);if([...rs,...vs].some(v=>v<0))throw new RangeError("ranges and volumes must be non-negative");const rangeScale=median(rs),volumeScale=median(vs);if(rangeScale<=0||volumeScale<=0)return {state:"zero-scale",range_scale:rangeScale,volume_scale:volumeScale};
  const expected=text(s.expected_prior_trend,"expected_prior_trend");if(!["uptrend","downtrend","any"].includes(expected))throw new RangeError("expected_prior_trend must be uptrend, downtrend, or any");const slope=(cs.at(-1)!-cs[0])/((lookback-1)*rangeScale),trendScore=expected==="any"?1:clamp(expected==="uptrend"?slope:-slope),volatilityRatio=number(s.current_range,"current_range")/rangeScale,volumeRatio=number(s.current_volume,"current_volume")/volumeScale;if(volatilityRatio<0)throw new RangeError("current_range must be non-negative");if(volumeRatio<0)throw new RangeError("current_volume must be non-negative");
  return {state:"ready",history_count:lookback,range_scale:rangeScale,volume_scale:volumeScale,normalized_slope:slope,trend_score:trendScore,volatility_ratio:volatilityRatio,volatility_score:clamp(1-Math.abs(volatilityRatio-1)/2),volume_ratio:volumeRatio,volume_score:clamp(volumeRatio/positive(s.target_volume_ratio??1.5,"target_volume_ratio"))};
}

function resolveConflicts(data:AnyMap):AnyMap {
  const s=object(data,"data"),rows=array(s.occurrences,"occurrences").map((raw,index)=>{const row={...object(raw,`occurrences[${index}]`)};for(const field of ["occurrence_id","instrument_id","interval","pattern_id"])row[field]=text(row[field],`occurrences[${index}].${field}`);row.direction=direction(row.direction,`occurrences[${index}].direction`);row.start_index=integer(row.start_index,`occurrences[${index}].start_index`,0);row.end_index=integer(row.end_index,`occurrences[${index}].end_index`,0);if(row.end_index<row.start_index)throw new RangeError("occurrence end cannot precede start");row.priority=integer(row.priority??0,`occurrences[${index}].priority`,0);row.confidence=number(row.confidence,`occurrences[${index}].confidence`);row.geometry_score=unit(row.geometry_score,`occurrences[${index}].geometry_score`);return row;}),groups=new Map<string,AnyMap[]>();
  for(const row of rows){const key=`${row.instrument_id}|${row.interval}`;groups.set(key,[...(groups.get(key)??[]),row]);}const winners:AnyMap[]=[],suppressed:AnyMap[]=[];
  for(const group of groups.values()){const ordered=[...group].sort((a,b)=>a.start_index-b.start_index||a.end_index-b.end_index||a.occurrence_id.localeCompare(b.occurrence_id)),components:AnyMap[][]=[];let current:AnyMap[]=[],currentEnd=-1;for(const row of ordered){if(current.length&&row.start_index>currentEnd){components.push(current);current=[];}current.push(row);currentEnd=Math.max(currentEnd,row.end_index);}if(current.length)components.push(current);components.forEach((component,componentIndex)=>{const ranked=[...component].sort((a,b)=>b.priority-a.priority||b.confidence-a.confidence||b.geometry_score-a.geometry_score||a.pattern_id.localeCompare(b.pattern_id)||a.occurrence_id.localeCompare(b.occurrence_id)),winner:AnyMap={...ranked[0],conflict_component:componentIndex,direction_conflict:new Set(component.map(r=>r.direction)).size>1};winners.push(winner);ranked.slice(1).forEach(loser=>suppressed.push({occurrence_id:loser.occurrence_id,winner_id:winner.occurrence_id,reason:"overlap-lower-precedence"}));});}
  winners.sort((a,b)=>[a.instrument_id,a.interval,String(a.start_index).padStart(12,"0"),a.occurrence_id].join("|").localeCompare([b.instrument_id,b.interval,String(b.start_index).padStart(12,"0"),b.occurrence_id].join("|")));suppressed.sort((a,b)=>a.occurrence_id.localeCompare(b.occurrence_id));return {state:"ready",winner_count:winners.length,suppressed_count:suppressed.length,winners,suppressed};
}

function runConfirmationStateMachine(data:AnyMap):AnyMap {
  const s=object(data,"data"),detectionIndex=integer(s.detection_index,"detection_index",0),d=direction(s.direction);if(d==="neutral")throw new RangeError("neutral candidates need a topic-specific state machine");const confirmation=number(s.confirmation_level,"confirmation_level"),invalidation=number(s.invalidation_level,"invalidation_level");if(d==="bullish"&&invalidation>=confirmation)throw new RangeError("bullish invalidation must be below confirmation");if(d==="bearish"&&invalidation<=confirmation)throw new RangeError("bearish invalidation must be above confirmation");const expires=integer(s.expires_after_bars,"expires_after_bars",1),transitions:AnyMap[]=[{bar_index:detectionIndex,from:"searching",to:"detected",reason:"geometry-matched"},{bar_index:detectionIndex,from:"detected",to:"awaiting-confirmation",reason:"levels-armed"}];let state="awaiting-confirmation",prior=detectionIndex;
  const events=array(s.events,"events");for(let eventIndex=0;eventIndex<events.length;eventIndex++){const event=object(events[eventIndex],`events[${eventIndex}]`),index=integer(event.bar_index,`events[${eventIndex}].bar_index`,detectionIndex+1);if(index<=prior)throw new RangeError("event bar indexes must be strictly increasing");prior=index;if(typeof event.bar_closed!=="boolean")throw new TypeError("event bar_closed must be boolean");if(!event.bar_closed){transitions.push({bar_index:index,from:state,to:state,reason:"provisional-bar-ignored"});continue;}const close=number(event.close,`events[${eventIndex}].close`),confirmed=d==="bullish"?close>=confirmation:close<=confirmation,invalidated=d==="bullish"?close<=invalidation:close>=invalidation;if(confirmed){transitions.push({bar_index:index,from:state,to:"confirmed",reason:"confirmation-close-crossed"});state="confirmed";break;}if(invalidated){transitions.push({bar_index:index,from:state,to:"invalidated",reason:"invalidation-close-crossed"});state="invalidated";break;}if(index>=detectionIndex+expires){transitions.push({bar_index:index,from:state,to:"expired",reason:"confirmation-window-ended"});state="expired";break;}transitions.push({bar_index:index,from:state,to:state,reason:"inside-active-band"});}
  return {state,direction:d,confirmation_level:confirmation,invalidation_level:invalidation,transitions,terminal:["confirmed","invalidated","expired"].includes(state)};
}

function rankAndDeduplicate(data:AnyMap):AnyMap {
  const s=object(data,"data"),halfLife=positive(s.recency_half_life_bars??5,"recency_half_life_bars"),dedupWindow=integer(s.dedup_window_bars??2,"dedup_window_bars",0),weights=object(s.weights??{confidence:.55,recency:.20,liquidity:.15,priority:.10},"weights"),names=["confidence","recency","liquidity","priority"];if(Object.keys(weights).sort().join("|")!==[...names].sort().join("|"))throw new RangeError("ranking weights must define confidence, recency, liquidity, and priority");const normalized:AnyMap={};for(const name of names)normalized[name]=number(weights[name],`weights.${name}`);const divisor=Object.values(normalized).reduce((sum:any,v:any)=>sum+v,0) as number;if(Object.values(normalized).some((v:any)=>v<0)||divisor<=0)throw new RangeError("ranking weights must be non-negative with a positive sum");
  const ranked=array(s.occurrences,"occurrences").map((raw,index)=>{const row={...object(raw,`occurrences[${index}]`)};for(const field of ["occurrence_id","instrument_id","interval","pattern_id","direction"])row[field]=text(row[field],`occurrences[${index}].${field}`);row.end_index=integer(row.end_index,`occurrences[${index}].end_index`,0);const confidence=number(row.confidence,`occurrences[${index}].confidence`);if(confidence<0||confidence>100)throw new RangeError("confidence must be in [0, 100]");const age=number(row.age_bars,`occurrences[${index}].age_bars`);if(age<0)throw new RangeError("age_bars must be non-negative");const components={confidence:confidence/100,recency:1/(1+age/halfLife),liquidity:unit(row.liquidity_score,`occurrences[${index}].liquidity_score`),priority:unit(row.priority_score,`occurrences[${index}].priority_score`)};row.rank_score=100*names.reduce((sum,name)=>sum+normalized[name]*components[name as keyof typeof components],0)/divisor;row.rank_components=components;return row;}).sort((a,b)=>b.rank_score-a.rank_score||a.occurrence_id.localeCompare(b.occurrence_id));
  const kept:AnyMap[]=[],suppressed:AnyMap[]=[];for(const row of ranked){const duplicate=kept.find(w=>w.instrument_id===row.instrument_id&&w.interval===row.interval&&w.pattern_id===row.pattern_id&&w.direction===row.direction&&Math.abs(w.end_index-row.end_index)<=dedupWindow);if(duplicate)suppressed.push({occurrence_id:row.occurrence_id,winner_id:duplicate.occurrence_id,reason:"same-pattern-within-dedup-window"});else kept.push(row);}kept.forEach((row,index)=>row.rank=index+1);return {state:"ready",ranked_count:kept.length,suppressed_count:suppressed.length,ranked:kept,suppressed};
}

const FUNCTIONS:AnyMap={"D06-F05-A01":buildRegistry,"D06-F05-A02":makeOccurrence,"D06-F05-A03":scanMarket,"D06-F05-A04":scoreContext,"D06-F05-A05":supportResistanceContext,"D06-F05-A06":trendVolatilityVolumeContext,"D06-F05-A07":resolveConflicts,"D06-F05-A08":runConfirmationStateMachine,"D06-F05-A09":rankAndDeduplicate};
function calculate(topicId:string,data:AnyMap):AnyMap { const fn=FUNCTIONS[topicId];if(!fn)throw new RangeError(`unsupported D06-F05 topic ${topicId}`);return fn(data); }