Overall Explainable Stock Score

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
226
227
228
229
230
231
232
233
234
235
236
237

/** Canonical TypeScript parity implementation for D18-F09. */

type RecordLike = Record<string, any>;
const finite = (value: any, name: string): number => {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  return value;
};
const positive = (data: RecordLike, name: string): number => {
  const value = finite(data[name], name);
  if (value <= 0) throw new RangeError(`${name} must be positive`);
  return value;
};
const nonnegative = (data: RecordLike, name: string): number => {
  const value = finite(data[name], name);
  if (value < 0) throw new RangeError(`${name} must be nonnegative`);
  return value;
};
const isoDate = (value: any, name: string): string => {
  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new TypeError(`${name} must be YYYY-MM-DD`);
  return value;
};
const clamp = (value: number, low = 0, high = 100): number => Math.max(low, Math.min(high, value));
const score = (data: RecordLike, name: string): number => {
  const value = finite(data[name], name);
  if (value < 0 || value > 100) throw new RangeError(`${name} must be between 0 and 100`);
  return value;
};
const band = (value: number): string => value >= 75 ? "strong" : value >= 50 ? "watch" : "weak";

function assemble(data: RecordLike): RecordLike {
  const cutoff = isoDate(data.knowledge_cutoff, "knowledge_cutoff");
  const periodEnd = isoDate(data.period_end, "period_end");
  if (typeof data.currency !== "string" || data.currency.length === 0) throw new TypeError("currency must be nonempty text");
  if (typeof data.scale !== "string" || data.scale.length === 0) throw new TypeError("scale must be nonempty text");
  if (!Array.isArray(data.required_fields) || data.required_fields.length === 0 || data.required_fields.some((x: any) => typeof x !== "string" || x.length === 0)) throw new TypeError("required_fields must be a nonempty string list");
  if (!Array.isArray(data.facts)) throw new TypeError("facts must be a list");
  const accepted: RecordLike = {};
  const rejected: RecordLike[] = [];
  for (const field of data.required_fields as string[]) {
    const candidates = (data.facts as any[]).filter((fact: any) => fact && fact.field === field && typeof fact.value === "number" && Number.isFinite(fact.value) && typeof fact.available_at === "string" && typeof fact.period_end === "string" && fact.available_at <= cutoff && fact.period_end === periodEnd && fact.currency === data.currency && fact.scale === data.scale && fact.revision === "original");
    if (candidates.length) {
      candidates.sort((a: any, b: any) => a.available_at.localeCompare(b.available_at));
      accepted[field] = candidates[candidates.length - 1].value;
    } else rejected.push({ field, reason: "no original, aligned fact available by the knowledge cutoff" });
  }
  const completeness = Object.keys(accepted).length / data.required_fields.length;
  return { state: completeness === 1 ? "ready" : "incomplete", method: "point-in-time-filing-fact-assembly", as_of: data.knowledge_cutoff, accepted_fields: Object.keys(accepted).sort(), selected_values: accepted, rejected_fields: rejected, completeness, ready: completeness === 1, clock_policy: "availability_at <= knowledge_cutoff; original revision; exact period/currency/scale" };
}

function cohort(data: RecordLike): RecordLike {
  const asOf = isoDate(data.as_of, "as_of");
  if (typeof data.target_id !== "string" || typeof data.target_sector !== "string" || typeof data.target_country !== "string") throw new TypeError("target identifiers and cohort dimensions must be text");
  const minCap = nonnegative(data, "min_market_cap");
  const minPeers = Math.trunc(positive(data, "min_peers"));
  if (!Array.isArray(data.universe) || data.universe.length === 0) throw new TypeError("universe must be a nonempty list");
  const target = (data.universe as any[]).find((row: any) => row && row.id === data.target_id);
  if (!target) throw new RangeError("target_id must occur in universe");
  const targetCap = positive(target, "market_cap");
  const eligible: any[] = [];
  const exclusions: RecordLike[] = [];
  for (const row of data.universe as any[]) {
    if (!row || row.id === data.target_id) continue;
    let reason: string | null = null;
    let cap = 0;
    try { cap = positive(row, "market_cap"); isoDate(row.available_at, "universe.available_at"); } catch { reason = "invalid market-cap or availability fact"; }
    if (!reason && row.available_at > asOf) reason = "not available at as-of date";
    else if (!reason && row.listed !== true) reason = "not listed under the selected scope";
    else if (!reason && row.sector !== data.target_sector) reason = "sector mismatch";
    else if (!reason && row.country !== data.target_country) reason = "country mismatch";
    else if (!reason && cap < minCap) reason = "below market-cap floor";
    if (reason) exclusions.push({ id: String(row?.id ?? "?"), reason }); else eligible.push(row);
  }
  eligible.sort((a, b) => Math.abs(a.market_cap - targetCap) - Math.abs(b.market_cap - targetCap) || String(a.id).localeCompare(String(b.id)));
  const ids = eligible.map(row => String(row.id));
  return { state: ids.length >= minPeers ? "resolved" : "abstain", method: "point-in-time-sector-country-market-cap-cohort", as_of: data.as_of, eligible_ids: ids, cohort_count: ids.length, minimum_required: minPeers, coverage: ids.length / minPeers, exclusions, tie_break: "absolute market-cap distance, then stable entity id" };
}

function normalize(data: RecordLike): RecordLike {
  if (!Array.isArray(data.metrics) || data.metrics.length === 0) throw new TypeError("metrics must be a nonempty list");
  const minPeers = Math.trunc(positive(data, "min_peers"));
  const results: RecordLike[] = [];
  for (const metric of data.metrics as any[]) {
    if (!metric || typeof metric.name !== "string" || !Array.isArray(metric.peers)) throw new TypeError("each metric needs name and peers");
    const target = finite(metric.target, "target");
    const peers = metric.peers.filter((value: any) => typeof value === "number" && Number.isFinite(value)) as number[];
    if (peers.length < minPeers) throw new RangeError(`${metric.name} has fewer than min_peers observations`);
    const equal = peers.filter(value => Math.abs(value - target) <= 1e-12).length;
    const less = peers.filter(value => value < target - 1e-12).length;
    const percentile = 100 * (less + 0.5 * equal) / peers.length;
    if (typeof metric.higher_is_better !== "boolean") throw new TypeError(`${metric.name}.higher_is_better must be boolean`);
    const normalized = metric.higher_is_better ? percentile : 100 - percentile;
    results.push({ name: metric.name, target, peer_count: peers.length, percentile, higher_is_better: metric.higher_is_better, normalized_score: normalized });
  }
  const aggregate = results.reduce((sum, row) => sum + row.normalized_score, 0) / results.length;
  return { state: "calculated", method: "midrank-empirical-percentile-with-direction", metrics: results, aggregate_score: aggregate, metric_count: results.length, invariant: "higher-is-better reverses the percentile only; peer values are not z-scored" };
}

const modelRules: Record<string, { population: string; eligible: (target: RecordLike) => boolean; variant: string }> = {
  altman_z_original: { population: "public industrial manufacturer", eligible: t => t.is_public === true && t.sector === "industrial" && Number(t.market_cap) > 0, variant: "Use D18-F04-A01 original public-manufacturer coefficients" },
  piotroski_f: { population: "non-financial issuer with two annual periods", eligible: t => !["bank", "insurance", "reit", "utility"].includes(t.sector) && Number(t.annual_periods) >= 2, variant: "Use D18-F04-A02 nine-signal contract" },
  beneish_m: { population: "non-financial issuer with two annual periods", eligible: t => !["bank", "insurance", "reit", "utility"].includes(t.sector) && Number(t.annual_periods) >= 2, variant: "Use D18-F04-A03 eight-index contract" },
  ohlson_o: { population: "industrial public research screen", eligible: t => t.is_public === true && Number(t.annual_periods) >= 2, variant: "Use D18-F04-A05 Model 1 convention" },
  dividend_safety: { population: "issuer with declared dividend and cash-flow facts", eligible: t => t.dividends_known === true && Number(t.annual_periods) >= 1, variant: "Use D18-F09-A07 payout contract" },
  balance_sheet_resilience: { population: "issuer with aligned balance-sheet and coverage facts", eligible: t => Number(t.total_assets) > 0 && ["US-GAAP", "IFRS"].includes(t.framework), variant: "Use D18-F09-A08 resilience contract" },
};

function route(data: RecordLike): RecordLike {
  if (!data.target || typeof data.target !== "object" || !Array.isArray(data.requested_models) || data.requested_models.length === 0) throw new TypeError("target and requested_models are required");
  const routes: RecordLike[] = [];
  for (const model of data.requested_models as any[]) {
    if (typeof model !== "string") throw new TypeError("requested model names must be text");
    const rule = modelRules[model];
    if (!rule) { routes.push({ model, status: "unsupported", variant: null, reason: "no frozen rule for this model label" }); continue; }
    const eligible = rule.eligible(data.target);
    routes.push({ model, status: eligible ? "eligible" : "reroute", variant: eligible ? rule.variant : null, population: rule.population, reason: eligible ? "all required scope facts pass" : `target does not meet ${rule.population} contract` });
  }
  const eligibleCount = routes.filter(row => row.status === "eligible").length;
  return { state: eligibleCount ? "routed" : "abstain", method: "explicit-model-applicability-router", routes, eligible_count: eligibleCount, requested_count: routes.length, coverage: eligibleCount / routes.length };
}

function weighted(data: RecordLike, names: string[], weights: number[], output: string, method: string): RecordLike {
  const values = names.map(name => score(data, name));
  const components: RecordLike = {}, weightMap: RecordLike = {}, contributions: RecordLike = {};
  names.forEach((name, i) => { components[name] = values[i]; weightMap[name] = weights[i]; contributions[name] = values[i] * weights[i]; });
  const total = Object.values(contributions).reduce((sum: number, value: any) => sum + value, 0);
  return { state: "calculated", method, components, weights: weightMap, contributions, [output]: total, band: band(total), coverage: 1 };
}
const health = (data: RecordLike): RecordLike => weighted(data, ["profitability_score", "cash_flow_score", "liquidity_score", "leverage_score"], [0.3, 0.3, 0.2, 0.2], "financial_health_score", "accounting-financial-health-weighted-composite");
const earnings = (data: RecordLike): RecordLike => weighted(data, ["accrual_quality_score", "cash_conversion_score", "revenue_quality_score", "manipulation_safety_score"], [0.3, 0.25, 0.25, 0.2], "earnings_quality_score", "earnings-quality-weighted-composite");

function dividend(data: RecordLike): RecordLike {
  const dividends = positive(data, "dividends_paid");
  const fcf = finite(data.free_cash_flow, "free_cash_flow");
  const netIncome = finite(data.net_income, "net_income");
  const interestCoverage = nonnegative(data, "interest_coverage");
  const cash = nonnegative(data, "cash_and_equivalents");
  const components = { free_cash_flow_coverage: clamp(fcf / dividends / 2 * 100), earnings_coverage: clamp(netIncome / dividends / 2 * 100), interest_coverage: clamp(interestCoverage / 10 * 100), cash_buffer: clamp(cash / dividends / 4 * 100) };
  const weights = { free_cash_flow_coverage: 0.35, earnings_coverage: 0.25, interest_coverage: 0.2, cash_buffer: 0.2 };
  const contributions: RecordLike = {}; Object.keys(components).forEach(key => { contributions[key] = (components as any)[key] * (weights as any)[key]; });
  const value = Object.values(contributions).reduce((sum: number, item: any) => sum + item, 0);
  return { state: "calculated", method: "coverage-and-liquidity-dividend-safety", components, weights, contributions, dividend_safety_score: value, band: band(value), coverage_policy: "coverage is capped at two times and cash buffer at four times" };
}

function resilience(data: RecordLike): RecordLike {
  const currentAssets = positive(data, "current_assets"), currentLiabilities = positive(data, "current_liabilities"), totalDebt = positive(data, "total_debt"), ebitda = positive(data, "ebitda"), interest = positive(data, "interest_expense"), cash = nonnegative(data, "cash_and_equivalents"), due = nonnegative(data, "debt_due_12m");
  if (due > totalDebt) throw new RangeError("debt_due_12m cannot exceed total_debt");
  const components = { liquidity: clamp(currentAssets / currentLiabilities / 2 * 100), net_leverage: clamp((1 - (totalDebt - cash) / (4 * ebitda)) * 100), interest_coverage: clamp(ebitda / interest / 10 * 100), maturity_headroom: clamp((1 - due / totalDebt) * 100) };
  const weights = { liquidity: 0.3, net_leverage: 0.3, interest_coverage: 0.25, maturity_headroom: 0.15 };
  const contributions: RecordLike = {}; Object.keys(components).forEach(key => { contributions[key] = (components as any)[key] * (weights as any)[key]; });
  const value = Object.values(contributions).reduce((sum: number, item: any) => sum + item, 0);
  return { state: "calculated", method: "liquidity-leverage-coverage-maturity-resilience", components, weights, contributions, balance_sheet_resilience_score: value, band: band(value) };
}

function ensemble(data: RecordLike): RecordLike {
  if (!Array.isArray(data.models) || data.models.length === 0) throw new TypeError("models must be a nonempty list");
  const eligible: [string, number, number][] = [];
  for (const model of data.models as any[]) {
    if (!model || typeof model !== "object") throw new TypeError("each model must be an object");
    if (model.eligible !== true) continue;
    const probability = finite(model.distress_probability, "distress_probability"), weight = positive(model, "weight");
    if (probability < 0 || probability > 1) throw new RangeError("distress_probability must be between zero and one");
    eligible.push([String(model.name ?? "model"), probability, weight]);
  }
  if (!eligible.length) throw new RangeError("at least one eligible model is required");
  const weightSum = eligible.reduce((sum, row) => sum + row[2], 0);
  const probability = eligible.reduce((sum, row) => sum + row[1] * row[2], 0) / weightSum;
  const variance = eligible.reduce((sum, row) => sum + row[2] * (row[1] - probability) ** 2, 0) / weightSum;
  const values = eligible.map(row => row[1]), dispersion = Math.max(...values) - Math.min(...values);
  return { state: "calculated", method: "weighted-distress-probability-ensemble", eligible_models: eligible.map(row => ({ name: row[0], probability: row[1], weight: row[2] })), model_count: eligible.length, distress_probability: probability, weighted_stddev: Math.sqrt(variance), disagreement_range: dispersion, agreement: 1 - dispersion, band: probability >= 0.66 ? "high-review" : probability >= 0.33 ? "watch" : "lower-review", calibration_boundary: "weighted aggregation preserves supplied probabilities; it does not recalibrate them" };
}

function conflict(data: RecordLike): RecordLike {
  if (!Array.isArray(data.components) || data.components.length === 0) throw new TypeError("components must be a nonempty list");
  const groupCap = finite(data.group_cap, "group_cap"), threshold = finite(data.conflict_threshold, "conflict_threshold");
  if (groupCap <= 0 || groupCap > 1 || threshold <= 0 || threshold > 100) throw new RangeError("group_cap must be in (0,1] and conflict_threshold in (0,100]");
  const groups = new Map<string, RecordLike[]>(); let rawWeight = 0, rawNumerator = 0;
  for (const item of data.components as any[]) {
    if (!item || typeof item.evidence_group !== "string") throw new TypeError("each component needs an evidence_group");
    const value = score(item, "score"), weight = positive(item, "weight"), group = item.evidence_group;
    if (!groups.has(group)) groups.set(group, []);
    groups.get(group)!.push({ name: String(item.name ?? "component"), score: value, weight }); rawWeight += weight; rawNumerator += value * weight;
  }
  const adjusted: RecordLike[] = [], conflicts: string[] = []; let denominator = 0, numerator = 0;
  [...groups.entries()].sort((a, b) => a[0].localeCompare(b[0])).forEach(([group, items]) => {
    const weight = items.reduce((sum, item) => sum + item.weight, 0), mean = items.reduce((sum, item) => sum + item.score * item.weight, 0) / weight, values = items.map(item => item.score), range = Math.max(...values) - Math.min(...values), isConflict = range >= threshold, capped = Math.min(weight, groupCap);
    if (isConflict) conflicts.push(group);
    adjusted.push({ group, raw_weight: weight, capped_weight: capped, mean_score: mean, range, conflict: isConflict }); denominator += capped; numerator += capped * mean;
  });
  const resolved = numerator / denominator, raw = rawNumerator / rawWeight;
  return { state: conflicts.length ? "conflict-detected" : "resolved", method: "evidence-group-cap-and-conflict-resolver", raw_score: raw, resolved_score: resolved, double_counting_adjustment: resolved - raw, groups: adjusted, conflict_groups: conflicts, conflict_count: conflicts.length, group_cap: groupCap, conflict_threshold: threshold };
}

const overall = (data: RecordLike): RecordLike => weighted(data, ["financial_health_score", "earnings_quality_score", "dividend_safety_score", "balance_sheet_resilience_score", "distress_safety_score", "valuation_score"], [0.24, 0.18, 0.14, 0.18, 0.16, 0.10], "overall_stock_score", "explainable-six-pillar-stock-score");

function confidence(data: RecordLike): RecordLike {
  const baseScore = score(data, "base_score"), required = Math.trunc(positive(data, "required_components")), available = Math.trunc(nonnegative(data, "available_components")), maxConflicts = Math.trunc(positive(data, "max_conflicts")), conflicts = Math.trunc(nonnegative(data, "conflict_count")), minimum = Math.trunc(positive(data, "minimum_components")), staleDays = nonnegative(data, "stale_days");
  if (available > required || conflicts > maxConflicts) throw new RangeError("available components or conflicts exceed their declared maxima");
  const coverage = available / required, missingPenalty = 1 - coverage, stalenessPenalty = Math.min(staleDays / 365, 1) * 0.2, conflictPenalty = Math.min(conflicts / maxConflicts, 1) * 0.2, confidenceValue = coverage * (1 - stalenessPenalty) * (1 - conflictPenalty), adjusted = clamp(baseScore - 15 * missingPenalty - 10 * conflictPenalty), abstain = available < minimum || confidenceValue < 0.6;
  return { state: abstain ? "abstain" : "usable-with-confidence", method: "coverage-staleness-conflict-confidence-gate", base_score: baseScore, coverage, missing_penalty: missingPenalty, staleness_penalty: stalenessPenalty, conflict_penalty: conflictPenalty, confidence: confidenceValue, adjusted_score: adjusted, abstain, reason: abstain ? "minimum component or confidence gate failed" : "coverage and confidence gates passed" };
}

function screen(data: RecordLike): RecordLike {
  if (!Array.isArray(data.universe) || data.universe.length === 0) throw new TypeError("universe must be a nonempty list");
  const floor = score(data, "screen_floor"), minConfidence = finite(data.min_confidence, "min_confidence"), minLiquidity = nonnegative(data, "min_liquidity");
  if (minConfidence < 0 || minConfidence > 1) throw new RangeError("min_confidence must be between zero and one");
  const selected: RecordLike[] = [], excluded: RecordLike[] = [];
  for (const row of data.universe as any[]) {
    if (!row || typeof row.id !== "string") throw new TypeError("each universe row needs an id");
    const rowScore = score(row, "score"), confidenceValue = finite(row.confidence, "confidence"), liquidity = nonnegative(row, "liquidity");
    if (confidenceValue < 0 || confidenceValue > 1) throw new RangeError("universe confidence must be between zero and one");
    const reasons: string[] = []; if (row.eligible !== true) reasons.push("not eligible"); if (rowScore < floor) reasons.push("below score floor"); if (confidenceValue < minConfidence) reasons.push("below confidence floor"); if (liquidity < minLiquidity) reasons.push("below liquidity floor");
    const candidate: RecordLike = { id: row.id, score: rowScore, confidence: confidenceValue, liquidity, sector: row.sector ?? "unspecified" };
    if (reasons.length) excluded.push({ ...candidate, reasons }); else selected.push(candidate);
  }
  selected.sort((a, b) => b.score - a.score || b.confidence - a.confidence || a.id.localeCompare(b.id));
  const ranked = selected.map((row, index) => ({ rank: index + 1, ...row }));
  return { state: selected.length ? "ranked" : "abstain", method: "eligibility-confidence-score-floor-ranking", ranked, screened_count: ranked.length, universe_count: data.universe.length, coverage: ranked.length / data.universe.length, score_floor: floor, confidence_floor: minConfidence, liquidity_floor: minLiquidity, excluded, tie_break: "score descending, confidence descending, stable id ascending" };
}

function history(data: RecordLike): RecordLike {
  if (!Array.isArray(data.history) || data.history.length < 2) throw new RangeError("history needs at least two points");
  const rows = (data.history as any[]).map(row => { if (!row || typeof row.components !== "object") throw new TypeError("each history row needs components"); return { date: isoDate(row.as_of, "history.as_of"), row }; });
  for (let index = 0; index + 1 < rows.length; index += 1) if (rows[index].date >= rows[index + 1].date) throw new RangeError("history must be strictly chronological");
  const previous = rows[rows.length - 2].row, latest = rows[rows.length - 1].row, previousScore = score(previous, "overall_score"), latestScore = score(latest, "overall_score");
  const keys = [...new Set([...Object.keys(previous.components), ...Object.keys(latest.components)])].sort();
  const deltas: RecordLike = {}; for (const key of keys) deltas[key] = score(latest.components, key) - score(previous.components, key);
  const topDriver = keys.reduce((best, key) => Math.abs(deltas[key]) > Math.abs(deltas[best]) || (Math.abs(deltas[key]) === Math.abs(deltas[best]) && key > best) ? key : best, keys[0]);
  const delta = latestScore - previousScore, priorBand = String(previous.band), latestBand = String(latest.band), migration = priorBand === latestBand ? "unchanged" : `${priorBand} -> ${latestBand}`, order: Record<string, number> = { abstain: 0, watch: 1, eligible: 2, strong: 3 };
  return { state: delta > 1e-12 ? "improved" : delta < -1e-12 ? "deteriorated" : "unchanged", method: "point-in-time-score-history-change-attribution", previous_as_of: previous.as_of, latest_as_of: latest.as_of, previous_score: previousScore, latest_score: latestScore, score_change: delta, prior_band: priorBand, latest_band: latestBand, migration, migration_direction: (order[latestBand] ?? 0) - (order[priorBand] ?? 0), component_deltas: deltas, top_driver: topDriver, clock_policy: "only knowledge-available snapshots are comparable" };
}

export function calculate(topicId: string, data: RecordLike): RecordLike {
  const functions: Record<string, (input: RecordLike) => RecordLike> = { "D18-F09-A01": assemble, "D18-F09-A02": cohort, "D18-F09-A03": normalize, "D18-F09-A04": route, "D18-F09-A05": health, "D18-F09-A06": earnings, "D18-F09-A07": dividend, "D18-F09-A08": resilience, "D18-F09-A09": ensemble, "D18-F09-A10": conflict, "D18-F09-A11": overall, "D18-F09-A12": confidence, "D18-F09-A13": screen, "D18-F09-A14": history };
  if (!functions[topicId]) throw new RangeError(`unsupported topic id: ${topicId}`);
  return functions[topicId](data);
}