Advance/Decline Ratio: Advancing Issues per Declining Issue

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

/** Correction-aware reference implementation for advancing issues / declining issues. */

export type EvidenceState = "resolved" | "incomplete" | "ambiguous" | "unsupported";
export type RatioState = "finite" | "no_declines" | "no_movers" | "empty_universe";
export type Direction = "advances_dominant" | "declines_dominant" | "balanced" | "advances_only" | "no_movers" | "no_universe";

export interface BreadthSnapshot {
  series_id: string; record_id: string; session_date: string;
  effective_at: string; available_at: string; venue_id: string;
  calendar_id: string; session_id: string; universe_id: string;
  universe_revision: string; listing_id_scheme: string;
  security_type_policy: string; comparison_basis: string;
  corporate_action_policy: string; revision: number; is_final: boolean;
  supersedes_record_id: string | null;
  advances: number; declines: number; unchanged: number;
  new_or_no_prior_close: number; halted: number; suspended: number;
  delisted: number; missing: number; unclassified: number; universe_size: number;
}

export interface BreadthQuery {
  session_date: string; decision_as_of: string; venue_id: string;
  universe_id: string; series_id: string;
  calendar_id: string; session_id: string; universe_revision: string;
  listing_id_scheme: string; security_type_policy: string;
  comparison_basis: string; corporate_action_policy: string;
}

export interface BreadthResult {
  evidence_state: EvidenceState; ratio_state: RatioState | null;
  advance_decline_ratio: number | null; direction: Direction | null;
  observed_partition_ratio: number | null; observed_partition_direction: Direction | null;
  selected_record_id: string | null; selected_revision: number | null;
  advances: number | null; declines: number | null; unchanged: number | null;
  excluded_count: number | null; universe_size: number | null;
  mover_count: number | null; classified_count: number | null;
  coverage_ratio: number | null; is_provisional: boolean | null;
  metric: "advancing_issues_divided_by_declining_issues"; reasons: string[];
}

export class BreadthValidationError extends Error {
  constructor(message: string) { super(message); this.name = "BreadthValidationError"; }
}

const TEXT_FIELDS = ["series_id", "record_id", "venue_id", "calendar_id", "session_id", "universe_id", "universe_revision", "listing_id_scheme", "security_type_policy", "comparison_basis", "corporate_action_policy"] as const;
const COUNT_FIELDS = ["advances", "declines", "unchanged", "new_or_no_prior_close", "halted", "suspended", "delisted", "missing", "unclassified", "universe_size"] as const;
const EXCLUSION_FIELDS = ["new_or_no_prior_close", "halted", "suspended", "delisted", "missing", "unclassified"] as const;
const QUERY_POLICY_FIELDS = ["calendar_id", "session_id", "universe_revision", "listing_id_scheme", "security_type_policy", "comparison_basis", "corporate_action_policy"] as const;
const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
const RFC3339_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;

function validDate(value: unknown, field: string): asserts value is string {
  if (typeof value !== "string" || !DATE_RE.test(value)) throw new BreadthValidationError(`${field} must be a valid YYYY-MM-DD date.`);
  const [y, m, d] = value.split("-").map(Number); const parsed = new Date(Date.UTC(y, m - 1, d));
  if (parsed.getUTCFullYear() !== y || parsed.getUTCMonth() !== m - 1 || parsed.getUTCDate() !== d) throw new BreadthValidationError(`${field} must be a valid YYYY-MM-DD date.`);
}

function validTimestamp(value: unknown, field: string): number {
  if (typeof value !== "string" || !RFC3339_RE.test(value) || Number.isNaN(Date.parse(value))) throw new BreadthValidationError(`${field} must be an RFC 3339 timestamp.`);
  return Date.parse(value);
}

function validCount(value: unknown, field: string): number {
  if (!Number.isSafeInteger(value) || (value as number) < 0) throw new BreadthValidationError(`${field} must be a non-negative cross-language safe integer.`);
  return value as number;
}

function validateSnapshot(snapshot: BreadthSnapshot): BreadthSnapshot {
  if (snapshot === null || typeof snapshot !== "object") throw new BreadthValidationError("snapshot must be an object.");
  validDate(snapshot.session_date, "session_date");
  const effective = validTimestamp(snapshot.effective_at, "effective_at");
  const available = validTimestamp(snapshot.available_at, "available_at");
  if (available < effective) throw new BreadthValidationError("available_at cannot precede effective_at.");
  for (const field of TEXT_FIELDS) if (typeof snapshot[field] !== "string" || snapshot[field].trim() === "") throw new BreadthValidationError(`${field} must be a non-empty string.`);
  if (snapshot.supersedes_record_id !== null && (typeof snapshot.supersedes_record_id !== "string" || snapshot.supersedes_record_id.trim() === "")) throw new BreadthValidationError("supersedes_record_id must be null or a non-empty string.");
  if (validCount(snapshot.revision, "revision") < 1) throw new BreadthValidationError("revision must be at least 1.");
  if (typeof snapshot.is_final !== "boolean") throw new BreadthValidationError("is_final must be a boolean.");
  const counts = Object.fromEntries(COUNT_FIELDS.map((f) => [f, validCount(snapshot[f], f)])) as Record<(typeof COUNT_FIELDS)[number], number>;
  const partition = COUNT_FIELDS.filter((f) => f !== "universe_size").reduce((sum, f) => sum + counts[f], 0);
  if (partition !== counts.universe_size) throw new BreadthValidationError("all classification buckets must sum exactly to universe_size.");
  return {...snapshot, ...counts};
}

export function calculateAdvanceDeclineRatio(snapshot: BreadthSnapshot): BreadthResult {
  const item = validateSnapshot(snapshot); const a = item.advances; const d = item.declines;
  const excluded = EXCLUSION_FIELDS.reduce((sum, f) => sum + item[f], 0);
  const movers = a + d; const classified = movers + item.unchanged;
  const coverage = item.universe_size === 0 ? null : classified / item.universe_size;
  let ratioState: RatioState; let ratio: number | null; let direction: Direction;
  if (item.universe_size === 0) { ratioState = "empty_universe"; ratio = null; direction = "no_universe"; }
  else if (movers === 0) { ratioState = "no_movers"; ratio = null; direction = "no_movers"; }
  else if (d === 0) { ratioState = "no_declines"; ratio = null; direction = "advances_only"; }
  else { ratioState = "finite"; ratio = a / d; direction = ratio > 1 ? "advances_dominant" : ratio < 1 ? "declines_dominant" : "balanced"; }
  const reasons: string[] = []; if (!item.is_final) reasons.push("snapshot_is_provisional"); if (excluded > 0) reasons.push("coverage_is_incomplete");
  const evidenceState: EvidenceState = reasons.length ? "incomplete" : "resolved";
  return {evidence_state: evidenceState, ratio_state: ratioState, advance_decline_ratio: evidenceState === "resolved" ? ratio : null,
    direction: evidenceState === "resolved" ? direction : null, observed_partition_ratio: ratio, observed_partition_direction: direction,
    selected_record_id: item.record_id, selected_revision: item.revision, advances: a, declines: d, unchanged: item.unchanged,
    excluded_count: excluded, universe_size: item.universe_size, mover_count: movers, classified_count: classified,
    coverage_ratio: coverage, is_provisional: !item.is_final, metric: "advancing_issues_divided_by_declining_issues", reasons};
}

function emptyResult(state: EvidenceState, reason: string): BreadthResult {
  return {evidence_state: state, ratio_state: null, advance_decline_ratio: null, direction: null, observed_partition_ratio: null, observed_partition_direction: null, selected_record_id: null, selected_revision: null,
    advances: null, declines: null, unchanged: null, excluded_count: null, universe_size: null, mover_count: null, classified_count: null,
    coverage_ratio: null, is_provisional: null, metric: "advancing_issues_divided_by_declining_issues", reasons: [reason]};
}

export function evaluateAdvanceDeclineRatioAsOf(snapshots: BreadthSnapshot[], query: BreadthQuery): BreadthResult {
  if (query === null || typeof query !== "object") throw new BreadthValidationError("query must be an object.");
  validDate(query.session_date, "query.session_date"); const decision = validTimestamp(query.decision_as_of, "query.decision_as_of");
  for (const field of ["venue_id", "universe_id", "series_id", ...QUERY_POLICY_FIELDS] as const) if (typeof query[field] !== "string" || query[field].trim() === "") throw new BreadthValidationError(`query.${field} must be a non-empty string.`);
  const eligible = snapshots.filter((raw) => {
    if (raw === null || typeof raw !== "object") throw new BreadthValidationError("each snapshot must be an object.");
    if (raw.session_date !== query.session_date || raw.venue_id !== query.venue_id || raw.universe_id !== query.universe_id || raw.series_id !== query.series_id || QUERY_POLICY_FIELDS.some((field) => raw[field] !== query[field])) return false;
    return validTimestamp(raw.available_at, "available_at") <= decision;
  }).map(validateSnapshot);
  if (!eligible.length) return emptyResult("unsupported", "no_snapshot_available_as_of_query");
  if (new Set(eligible.map((item) => item.record_id)).size !== eligible.length) return emptyResult("ambiguous", "duplicate_record_id");
  const highest = Math.max(...eligible.map((item) => item.revision));
  const byRevision = new Map<number, BreadthSnapshot[]>(); for (const item of eligible) byRevision.set(item.revision, [...(byRevision.get(item.revision) ?? []), item]);
  for (let revision = 1; revision <= highest; revision += 1) if (!byRevision.has(revision)) return emptyResult("ambiguous", "non_contiguous_revision_chain");
  if ([...byRevision.values()].some((items) => items.length !== 1)) return emptyResult("ambiguous", "conflicting_highest_revision");
  for (let revision = 1; revision <= highest; revision += 1) { const current = byRevision.get(revision)![0]; const expected = revision === 1 ? null : byRevision.get(revision - 1)![0].record_id; if (current.supersedes_record_id !== expected) return emptyResult("ambiguous", "broken_supersession_chain"); }
  return calculateAdvanceDeclineRatio(byRevision.get(highest)![0]);
}