McClellan Volume Summation Index

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

/** Reference implementation for McClellan Volume Summation Index. */
export type RecordRow = Record<string, unknown>;
export const MODE = "raw_volume_sum";
export const INITIAL_INDEX: number | null = 0.0;
const FAST_ALPHA = 0.10;
const SLOW_ALPHA = 0.05;
const IDENTITY_FIELDS = ["venue_id", "universe_id", "methodology_id", "calendar_id", "volume_unit", "volume_adjustment_basis"] as const;

function numberValue(value: unknown, name: string): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${name} must be a finite number`);
  return value;
}

function timestamp(value: unknown, name: string): number {
  if (typeof value !== "string" || !value.endsWith("Z")) throw new Error(`${name} must be an RFC 3339 UTC timestamp ending in Z`);
  const parsed = Date.parse(value);
  if (!Number.isFinite(parsed)) throw new Error(`${name} is invalid`);
  return parsed;
}

export function transformRecord(record: RecordRow): number {
  if (MODE.startsWith("ratio_issue")) {
    const advances = numberValue(record.advances, "advances");
    const declines = numberValue(record.declines, "declines");
    if (advances < 0 || declines < 0) throw new Error("issue counts must be non-negative");
    const denominator = advances + declines;
    if (denominator === 0) throw new Error("ratio-adjusted breadth is undefined when advances + declines is zero");
    return 1000 * (advances - declines) / denominator;
  }
  if (MODE.startsWith("raw_issue")) {
    const advances = numberValue(record.advances, "advances");
    const declines = numberValue(record.declines, "declines");
    if (advances < 0 || declines < 0) throw new Error("issue counts must be non-negative");
    return advances - declines;
  }
  const up = numberValue(record.up_volume, "up_volume");
  const down = numberValue(record.down_volume, "down_volume");
  const unchanged = numberValue(record.unchanged_volume, "unchanged_volume");
  const total = numberValue(record.total_volume, "total_volume");
  if (Math.min(up, down, unchanged, total) < 0) throw new Error("volume fields must be non-negative");
  if (total <= 0 || up + down + unchanged !== total) throw new Error("volume partition must be positive and reconcile exactly");
  return up - down;
}

export function calculateValues(values: readonly number[]) {
  const data = values.map((value) => numberValue(value, "input value"));
  let fast: number | null = null;
  let slow: number | null = null;
  let indexState = INITIAL_INDEX;
  return data.map((value, offset) => {
    const position = offset + 1;
    if (position === 19) fast = data.slice(0, 19).reduce((a, b) => a + b, 0) / 19;
    else if (position > 19) fast = fast! + FAST_ALPHA * (value - fast!);
    if (position === 39) slow = data.slice(0, 39).reduce((a, b) => a + b, 0) / 39;
    else if (position > 39) slow = slow! + SLOW_ALPHA * (value - slow!);
    const oscillator = slow === null ? null : fast! - slow;
    let indexValue: number | null = null;
    if (oscillator !== null && INITIAL_INDEX !== null) {
      indexState = indexState! + oscillator;
      indexValue = indexState;
    }
    return {
      observation: position, input_value: value, fast_ema: fast, slow_ema: slow,
      oscillator, index_value: indexValue,
      status: position < 19 ? "warming_fast" : position < 39 ? "warming_slow" : "ready",
    };
  });
}

export function calculate(records: readonly RecordRow[], cutoff: string) {
  const cutoffTime = timestamp(cutoff, "cutoff");
  const retained: RecordRow[] = [];
  let ignoredFuture = 0;
  for (const record of records) {
    if (timestamp(record.available_at, "available_at") > cutoffTime) ignoredFuture += 1;
    else retained.push(record);
  }
  if (!retained.length) return {status: "incomplete", reason_codes: ["no_evidence_at_cutoff"], points: [], ignored_future_records: ignoredFuture};

  const groups = new Map<number, RecordRow[]>();
  for (const record of retained) {
    const sequence = record.session_sequence;
    const revision = record.revision;
    if (!Number.isInteger(sequence) || (sequence as number) <= 0) throw new Error("session_sequence must be a positive integer");
    if (!Number.isInteger(revision) || (revision as number) < 0) throw new Error("revision must be a non-negative integer");
    const bucket = groups.get(sequence as number) ?? [];
    bucket.push(record);
    groups.set(sequence as number, bucket);
  }
  const sequences = [...groups.keys()].sort((a, b) => a - b);
  for (let i = 1; i < sequences.length; i += 1) {
    if (sequences[i] !== sequences[i - 1] + 1) return {status: "incomplete", reason_codes: ["missing_session_sequence"], points: [], ignored_future_records: ignoredFuture};
  }
  const resolved: RecordRow[] = [];
  let identity: string | null = null;
  for (const sequence of sequences) {
    const revisions = groups.get(sequence)!;
    const numbers = revisions.map((row) => row.revision as number);
    if (new Set(numbers).size !== numbers.length) return {status: "ambiguous", reason_codes: ["duplicate_revision"], points: [], ignored_future_records: ignoredFuture};
    const sorted = [...numbers].sort((a, b) => a - b);
    if (sorted.some((value, index) => value !== index)) return {status: "ambiguous", reason_codes: ["broken_revision_chain"], points: [], ignored_future_records: ignoredFuture};
    const head = revisions.reduce((a, b) => (a.revision as number) > (b.revision as number) ? a : b);
    if (head.event_type === "cancel") return {status: "incomplete", reason_codes: ["cancelled_session"], points: [], ignored_future_records: ignoredFuture};
    if (head.source_evidence_state !== "ready") return {status: "incomplete", reason_codes: ["source_not_ready"], points: [], ignored_future_records: ignoredFuture};
    const currentIdentity = IDENTITY_FIELDS.map((field) => head[field]);
    if (currentIdentity.some((value) => typeof value !== "string" || !value)) throw new Error("series identity fields must be non-empty strings");
    const encoded = JSON.stringify(currentIdentity);
    if (identity === null) identity = encoded;
    else if (identity !== encoded) return {status: "unsupported", reason_codes: ["series_identity_break"], points: [], ignored_future_records: ignoredFuture};
    transformRecord(head);
    resolved.push(head);
  }
  const points = calculateValues(resolved.map(transformRecord)).map((point, index) => ({...point, session_date: resolved[index].session_date}));
  return {
    status: "resolved", reason_codes: [], points,
    latest_oscillator: points.at(-1)?.oscillator ?? null,
    latest_index_value: points.at(-1)?.index_value ?? null,
    ignored_future_records: ignoredFuture, seed_policy: "sma_19_39", initial_index: INITIAL_INDEX,
  };
}