Price-by-Volume Profile Construction

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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225

/** Reference algorithms for D08-F06. Repository teaching conventions only. */

type Row = Record<string, any>;

function numberValue(value: unknown, name: string, minimum?: number): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (minimum !== undefined && value < minimum) throw new RangeError(`${name} must be >= ${minimum}`);
  return value;
}

function integerValue(value: unknown, name: string, minimum = 0): number {
  const result = numberValue(value, name);
  if (!Number.isInteger(result) || result < minimum) throw new RangeError(`${name} must be an integer >= ${minimum}`);
  return result;
}

function timeValue(value: unknown, name: string): number {
  if (typeof value !== "string" || !/(Z|[+-]\d\d:\d\d)$/.test(value)) throw new TypeError(`${name} must be a zoned ISO-8601 string`);
  const result = Date.parse(value);
  if (!Number.isFinite(result)) throw new RangeError(`${name} must be a zoned ISO-8601 string`);
  return result;
}

function rounded(value: number): number { return Number(value.toFixed(12)); }

function alignedTicks(price: unknown, tick: number, name: string): number {
  const value = numberValue(price, name);
  const ticks = Math.round(value / tick);
  if (Math.abs(value - ticks * tick) > tick * 1e-8) throw new RangeError(`${name} must align to tick_size`);
  return ticks;
}

function median(values: number[]): number {
  const ordered = [...values].sort((a, b) => a - b);
  const middle = Math.floor(ordered.length / 2);
  return ordered.length % 2 ? ordered[middle] : (ordered[middle - 1] + ordered[middle]) / 2;
}

function profile(input: Row): Row {
  const tick = numberValue(input.tick_size, "tick_size", 1e-12);
  const widthTicks = integerValue(input.bin_size_ticks, "bin_size_ticks", 1);
  const windowEnd = timeValue(input.window_end, "window_end");
  if (!Array.isArray(input.trades) || input.trades.length === 0) throw new RangeError("trades must be non-empty");
  const seen = new Set<string>();
  const volumes = new Map<number, number>();
  let previous: number | null = null, total = 0, eligible = 0;
  input.trades.forEach((trade: Row, index: number) => {
    if (!trade || typeof trade !== "object") throw new TypeError("each trade must be an object");
    if (typeof trade.trade_id !== "string" || !trade.trade_id || seen.has(trade.trade_id)) throw new RangeError("trade_id must be unique");
    seen.add(trade.trade_id);
    if (trade.final !== true) throw new RangeError("all trades must be final");
    const timestamp = timeValue(trade.timestamp, `trades[${index}].timestamp`);
    if (timestamp > windowEnd || (previous !== null && timestamp < previous)) throw new RangeError("trades must be ordered and available");
    previous = timestamp;
    const priceTicks = alignedTicks(trade.price, tick, `trades[${index}].price`);
    const volume = numberValue(trade.volume, `trades[${index}].volume`, 0);
    if (volume === 0) return;
    eligible += 1; total += volume;
    const binIndex = Math.floor(priceTicks / widthTicks);
    volumes.set(binIndex, (volumes.get(binIndex) ?? 0) + volume);
  });
  if (total <= 0) throw new RangeError("eligible volume must be positive");
  const rows = [...volumes.keys()].sort((a, b) => a - b).map(binIndex => {
    const lowerTicks = binIndex * widthTicks, lower = lowerTicks * tick, upper = (lowerTicks + widthTicks) * tick;
    const volume = volumes.get(binIndex)!;
    return { bin_index: binIndex, lower: rounded(lower), upper: rounded(upper), midpoint: rounded((lower + upper) / 2), volume: rounded(volume), share: rounded(volume / total) };
  });
  return { state: "calculated", tick_size: tick, bin_size_ticks: widthTicks, bin_width: rounded(widthTicks * tick), total_volume: rounded(total), trade_count: input.trades.length, eligible_trade_count: eligible, rows };
}

function profileFeatures(input: Row): Row {
  if (!Array.isArray(input.profile_rows) || input.profile_rows.length < 3) throw new RangeError("profile_rows must contain at least three rows");
  const fraction = numberValue(input.value_area_fraction, "value_area_fraction");
  const hvnRatio = numberValue(input.hvn_median_ratio, "hvn_median_ratio", 1);
  const lvnRatio = numberValue(input.lvn_median_ratio, "lvn_median_ratio");
  if (!(fraction > 0 && fraction <= 1) || lvnRatio < 0 || lvnRatio > 1) throw new RangeError("fractions outside canonical range");
  let previousUpper: number | null = null;
  const rows = input.profile_rows.map((row: Row, index: number) => {
    const lower = numberValue(row.lower, `profile_rows[${index}].lower`), upper = numberValue(row.upper, `profile_rows[${index}].upper`), volume = numberValue(row.volume, `profile_rows[${index}].volume`, 0);
    if (upper <= lower || (previousUpper !== null && Math.abs(lower - previousUpper) > 1e-9)) throw new RangeError("profile rows must be ordered and contiguous");
    previousUpper = upper; return { lower, upper, midpoint: (lower + upper) / 2, volume };
  });
  const total = rows.reduce((sum: number, row: Row) => sum + row.volume, 0);
  if (total <= 0) throw new RangeError("profile volume must be positive");
  const profileMidpoint = (rows[0].lower + rows[rows.length - 1].upper) / 2;
  const maximum = Math.max(...rows.map((row: Row) => row.volume));
  const candidates = rows.map((row: Row, i: number) => row.volume === maximum ? i : -1).filter((i: number) => i >= 0);
  candidates.sort((a: number, b: number) => Math.abs(rows[a].midpoint - profileMidpoint) - Math.abs(rows[b].midpoint - profileMidpoint) || rows[a].midpoint - rows[b].midpoint);
  const pocIndex = candidates[0], included = new Set<number>([pocIndex]), trace = [pocIndex];
  let cumulative = rows[pocIndex].volume, low = pocIndex, high = pocIndex;
  const target = total * fraction;
  while (cumulative < target && (low > 0 || high < rows.length - 1)) {
    const below = low > 0 ? low - 1 : null, above = high < rows.length - 1 ? high + 1 : null;
    let chosen: number;
    if (below === null) chosen = above!; else if (above === null) chosen = below; else chosen = rows[above].volume >= rows[below].volume ? above : below;
    included.add(chosen); cumulative += rows[chosen].volume; low = Math.min(low, chosen); high = Math.max(high, chosen); trace.push(chosen);
  }
  const positiveMedian = median(rows.filter((row: Row) => row.volume > 0).map((row: Row) => row.volume));
  const hvn: Row[] = [], lvn: Row[] = [];
  for (let i = 1; i < rows.length - 1; i += 1) {
    const current = rows[i].volume, item = { price: rounded(rows[i].midpoint), volume: rounded(current), median_ratio: rounded(current / positiveMedian) };
    if (current > rows[i - 1].volume && current >= rows[i + 1].volume && current >= positiveMedian * hvnRatio) hvn.push(item);
    if (current < rows[i - 1].volume && current <= rows[i + 1].volume && current <= positiveMedian * lvnRatio) lvn.push(item);
  }
  return { state: "calculated", poc_index: pocIndex, poc_price: rounded(rows[pocIndex].midpoint), poc_volume: rounded(maximum), value_area_low: rounded(rows[low].lower), value_area_high: rounded(rows[high].upper), value_area_volume: rounded(cumulative), value_area_share: rounded(cumulative / total), target_share: fraction, included_indices: [...included].sort((a, b) => a - b), expansion_trace: trace, hvn, lvn };
}

function fibonacci(input: Row): Row {
  const start = numberValue(input.start_price, "start_price"), end = numberValue(input.end_price, "end_price"), correction = numberValue(input.retracement_end_price, "retracement_end_price"), tick = numberValue(input.tick_size, "tick_size", 1e-12);
  if (start === end || !Array.isArray(input.retracement_ratios) || !input.retracement_ratios.length || !Array.isArray(input.extension_ratios) || !input.extension_ratios.length) throw new RangeError("invalid anchors or ratios");
  const rr = input.retracement_ratios.map((v: unknown) => numberValue(v, "retracement ratio")), er = input.extension_ratios.map((v: unknown) => numberValue(v, "extension ratio"));
  if (rr.some((v: number) => v < 0 || v > 1) || er.some((v: number) => v < 0)) throw new RangeError("ratios outside canonical ranges");
  const direction = end > start ? 1 : -1, magnitude = Math.abs(end - start), snap = (value: number) => {
    const tickUnits = value / tick, roundedUnits = Math.sign(tickUnits) * Math.floor(Math.abs(tickUnits) + 0.5);
    return rounded(roundedUnits * tick);
  };
  return { state: "calculated", direction: direction > 0 ? "up" : "down", leg_size: rounded(magnitude), retracement_levels: rr.map((ratio: number) => ({ ratio, raw_price: rounded(end - direction * ratio * magnitude), price: snap(end - direction * ratio * magnitude) })), extension_levels: er.map((ratio: number) => ({ ratio, raw_price: rounded(correction + direction * ratio * magnitude), price: snap(correction + direction * ratio * magnitude) })), rounding: "nearest tick, half away from zero" };
}

function roundNumbers(input: Row): Row {
  const current = numberValue(input.current_price, "current_price"), lower = numberValue(input.lower_bound, "lower_bound"), upper = numberValue(input.upper_bound, "upper_bound"), tick = numberValue(input.tick_size, "tick_size", 1e-12), unit = numberValue(input.base_unit, "base_unit", tick);
  if (lower > current || current > upper || lower >= upper) throw new RangeError("invalid bounds");
  const unitTicks = alignedTicks(unit, tick, "base_unit"), lowerTicks = Math.ceil(lower / tick - 1e-9), upperTicks = Math.floor(upper / tick + 1e-9), first = Math.ceil(lowerTicks / unitTicks) * unitTicks;
  const levels: Row[] = [];
  for (let priceTicks = first; priceTicks <= upperTicks; priceTicks += unitTicks) {
    const multiple = Math.round(priceTicks / unitTicks), major = multiple % 10 === 0, half = multiple % 5 === 0, price = priceTicks * tick, weight = major ? 1 : half ? 0.75 : 0.5;
    levels.push({ price: rounded(price), class: major ? "major" : half ? "half" : "minor", salience_weight: weight, distance: rounded(Math.abs(price - current)), distance_bps: current === 0 ? null : rounded(Math.abs(price - current) / Math.abs(current) * 10000) });
  }
  if (!levels.length) throw new RangeError("bounds contain no levels");
  const closest = [...levels].sort((a, b) => a.distance - b.distance || b.salience_weight - a.salience_weight || a.price - b.price)[0];
  return { state: "calculated", base_unit: unit, level_count: levels.length, closest_level: closest, levels };
}

function fusion(input: Row): Row {
  if (!Array.isArray(input.levels) || !input.levels.length) throw new RangeError("levels must be non-empty");
  const tolerance = numberValue(input.fusion_tolerance, "fusion_tolerance", 0), minimumSources = integerValue(input.minimum_sources, "minimum_sources", 1), seen = new Set<string>();
  const parsed = input.levels.map((level: Row, index: number) => {
    if (typeof level.level_id !== "string" || !level.level_id || seen.has(level.level_id) || typeof level.source !== "string" || !level.source) throw new RangeError("level identity/source invalid");
    seen.add(level.level_id); return { level_id: level.level_id, source: level.source, price: numberValue(level.price, `levels[${index}].price`), weight: numberValue(level.weight, `levels[${index}].weight`, 0) };
  }).sort((a: Row, b: Row) => a.price - b.price || a.source.localeCompare(b.source) || a.level_id.localeCompare(b.level_id));
  const clusters: Row[][] = [];
  parsed.forEach((level: Row) => { if (!clusters.length || level.price - clusters[clusters.length - 1][0].price > 2 * tolerance) clusters.push([level]); else clusters[clusters.length - 1].push(level); });
  const zones: Row[] = [], rejected_clusters: Row[] = [];
  clusters.forEach((cluster, index) => {
    const sources = [...new Set(cluster.map(row => row.source))].sort(), weightSum = cluster.reduce((sum, row) => sum + row.weight, 0), center = weightSum > 0 ? cluster.reduce((sum, row) => sum + row.price * row.weight, 0) / weightSum : cluster.reduce((sum, row) => sum + row.price, 0) / cluster.length;
    const item = { zone_id: `Z${String(index + 1).padStart(2, "0")}`, lower: rounded(Math.min(...cluster.map(row => row.price)) - tolerance), upper: rounded(Math.max(...cluster.map(row => row.price)) + tolerance), center: rounded(center), source_count: sources.length, sources, weight_sum: rounded(weightSum), member_ids: cluster.map(row => row.level_id) };
    if (sources.length >= minimumSources) zones.push(item); else rejected_clusters.push({ ...item, reason: "insufficient-distinct-sources" });
  });
  zones.sort((a, b) => b.source_count - a.source_count || b.weight_sum - a.weight_sum || a.center - b.center);
  return { state: "calculated", zones, rejected_clusters, fusion_tolerance: tolerance, minimum_sources: minimumSources };
}

function strength(input: Row): Row {
  const source = numberValue(input.source_confluence, "source_confluence"), age = integerValue(input.zone_age_bars, "zone_age_bars"), halfLife = numberValue(input.half_life_bars, "half_life_bars", 1e-12), breakCount = integerValue(input.break_count, "break_count"), rejectionTarget = numberValue(input.rejection_target_atr, "rejection_target_atr", 1e-12);
  if (source < 0 || source > 1 || !Array.isArray(input.touches)) throw new RangeError("invalid source or touches");
  const decayed = input.touches.map((touch: Row, index: number) => { const touchAge = integerValue(touch.age_bars, `touches[${index}].age_bars`), rejection = numberValue(touch.rejection_atr, `touches[${index}].rejection_atr`, 0); return [0.5 ** (touchAge / halfLife), Math.min(rejection / rejectionTarget, 1)]; });
  const evidence = decayed.reduce((sum: number, value: number[]) => sum + value[0], 0), sourceComponent = 30 * source, touchComponent = 35 * (1 - Math.exp(-evidence)), rejectionComponent = evidence === 0 ? 0 : 25 * decayed.reduce((sum: number, value: number[]) => sum + value[0] * value[1], 0) / evidence, durabilityComponent = 10 * (0.5 ** (age / halfLife)), penalty = Math.min(30, 15 * breakCount), score = Math.max(0, Math.min(100, sourceComponent + touchComponent + rejectionComponent + durabilityComponent - penalty));
  return { state: "calculated", score: rounded(score), grade: score >= 75 ? "strong" : score >= 50 ? "moderate" : score >= 25 ? "weak" : "depleted", components: { source: rounded(sourceComponent), touch: rounded(touchComponent), rejection: rounded(rejectionComponent), durability: rounded(durabilityComponent), break_penalty: rounded(penalty) }, decayed_touch_evidence: rounded(evidence), touch_count: input.touches.length };
}

function roleReversal(input: Row): Row {
  const lower = numberValue(input.zone_lower, "zone_lower"), upper = numberValue(input.zone_upper, "zone_upper"), buffer = numberValue(input.break_buffer, "break_buffer", 0), confirmations = integerValue(input.confirmation_closes, "confirmation_closes", 1);
  if (lower >= upper || !["support", "resistance"].includes(input.initial_role) || !Array.isArray(input.closes) || !input.closes.length) throw new RangeError("invalid role-reversal input");
  const values = input.closes.map((value: unknown) => numberValue(value, "close")); let role = input.initial_role, state = `active-${role}`, outsideCount = 0, retestSeen = false; const transitions: Row[] = [];
  values.forEach((close: number, index: number) => {
    const side = close > upper + buffer ? "above" : close < lower - buffer ? "below" : "zone", previous = state;
    if (state === "active-support") { outsideCount = side === "below" ? outsideCount + 1 : 0; if (outsideCount >= confirmations) { state = "awaiting-resistance-retest"; outsideCount = 0; } }
    else if (state === "active-resistance") { outsideCount = side === "above" ? outsideCount + 1 : 0; if (outsideCount >= confirmations) { state = "awaiting-support-retest"; outsideCount = 0; } }
    else if (state === "awaiting-resistance-retest") { if (side === "zone") retestSeen = true; else if (retestSeen && side === "below") { state = "confirmed-resistance"; role = "resistance"; } else if (side === "above") state = "invalidated"; }
    else if (state === "awaiting-support-retest") { if (side === "zone") retestSeen = true; else if (retestSeen && side === "above") { state = "confirmed-support"; role = "support"; } else if (side === "below") state = "invalidated"; }
    if (state !== previous) transitions.push({ index, close, from: previous, to: state, side });
  });
  return { state, final_role: state === "invalidated" ? "none" : role, confirmed: state.startsWith("confirmed-"), retest_seen: retestSeen, transitions, observations: values.length };
}

function breakoutRetest(input: Row): Row {
  const lower = numberValue(input.zone_lower, "zone_lower"), upper = numberValue(input.zone_upper, "zone_upper"), buffer = numberValue(input.break_buffer, "break_buffer", 0), tolerance = numberValue(input.retest_tolerance, "retest_tolerance", 0), needed = integerValue(input.breakout_closes, "breakout_closes", 1), maxBars = integerValue(input.max_retest_bars, "max_retest_bars", 1), direction = input.direction;
  if (lower >= upper || !["up", "down"].includes(direction) || !Array.isArray(input.bars) || !input.bars.length) throw new RangeError("invalid breakout input");
  let state = "searching", count = 0, breakout_index: number | null = null, retest_index: number | null = null, confirmation_index: number | null = null; const transitions: Row[] = [];
  input.bars.forEach((bar: Row, index: number) => {
    const high = numberValue(bar.high, "bar.high"), low = numberValue(bar.low, "bar.low"), close = numberValue(bar.close, "bar.close");
    if (high < Math.max(low, close) || low > Math.min(high, close)) throw new RangeError("inconsistent bar");
    const previous = state, beyond = direction === "up" ? close > upper + buffer : close < lower - buffer, failed = direction === "up" ? close < lower - buffer : close > upper + buffer, contact = low <= upper + tolerance && high >= lower - tolerance;
    if (state === "searching" || state === "breakout-pending") { count = beyond ? count + 1 : 0; state = count ? "breakout-pending" : "searching"; if (count >= needed) { breakout_index = index; state = "awaiting-retest"; } }
    else if (state === "awaiting-retest") { if (breakout_index !== null && index - breakout_index > maxBars) state = "expired"; else if (failed) state = "failed"; else if (contact) { retest_index = index; state = "retest-contact"; } }
    else if (state === "retest-contact") { if (failed) state = "failed"; else if (beyond) { confirmation_index = index; state = "confirmed"; } else if (breakout_index !== null && index - breakout_index > maxBars) state = "expired"; }
    if (state !== previous) transitions.push({ index, from: previous, to: state, close });
  });
  return { state, confirmed: state === "confirmed", direction, breakout_index, retest_index, confirmation_index, transitions };
}

function scanner(input: Row): Row {
  const asOf = timeValue(input.as_of, "as_of"), maxBps = numberValue(input.max_distance_bps, "max_distance_bps", 0), halfLife = numberValue(input.freshness_half_life_hours, "freshness_half_life_hours", 1e-12);
  if (!Array.isArray(input.instruments) || !input.instruments.length) throw new RangeError("instruments must be non-empty");
  const seen = new Set<string>(), ranked: Row[] = [];
  input.instruments.forEach((item: Row, index: number) => {
    if (typeof item.instrument_id !== "string" || !item.instrument_id || seen.has(item.instrument_id)) throw new RangeError("instrument_id must be unique"); seen.add(item.instrument_id);
    const price = numberValue(item.current_price, `instruments[${index}].current_price`, 1e-12), lower = numberValue(item.zone_lower, "zone_lower"), upper = numberValue(item.zone_upper, "zone_upper"), zoneStrength = numberValue(item.zone_strength, "zone_strength"), observed = timeValue(item.observed_at, "observed_at");
    if (lower >= upper || zoneStrength < 0 || zoneStrength > 100 || observed > asOf) throw new RangeError("invalid point-in-time zone record");
    const distance = price < lower ? lower - price : price > upper ? price - upper : 0, distanceBps = distance / price * 10000, ageHours = (asOf - observed) / 3600000, freshness = 0.5 ** (ageHours / halfLife), proximity = maxBps > 0 ? Math.max(0, 1 - distanceBps / maxBps) : distanceBps === 0 ? 1 : 0, score = 100 * (0.55 * proximity + 0.30 * zoneStrength / 100 + 0.15 * freshness);
    if (distanceBps <= maxBps) ranked.push({ instrument_id: item.instrument_id, current_price: price, zone_lower: lower, zone_upper: upper, inside_zone: distance === 0, distance: rounded(distance), distance_bps: rounded(distanceBps), strength: zoneStrength, freshness: rounded(freshness), rank_score: rounded(score) });
  });
  ranked.sort((a, b) => b.rank_score - a.rank_score || a.distance_bps - b.distance_bps || a.instrument_id.localeCompare(b.instrument_id)); ranked.forEach((row, index) => { row.rank = index + 1; });
  return { state: "calculated", as_of: input.as_of, eligible_count: ranked.length, ranked };
}

const calculators: Record<string, (input: Row) => Row> = {
  "D08-F06-A01": profile,
  "D08-F06-A02": profileFeatures,
  "D08-F06-A03": fibonacci,
  "D08-F06-A04": roundNumbers,
  "D08-F06-A05": fusion,
  "D08-F06-A06": strength,
  "D08-F06-A07": roleReversal,
  "D08-F06-A08": breakoutRetest,
  "D08-F06-A09": scanner,
};

export function calculate(topicId: string, input: Row): Row {
  const calculator = calculators[topicId];
  if (!calculator) throw new RangeError(`unsupported topic_id: ${topicId}`);
  if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("inputs must be an object");
  return calculator(input);
}