Cash-Dividend Total-Return Adjustment: From Price Drop to Exact Return

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

/** Auditable ex-date-close cash-dividend total-return adjustment. */
const DECIMALS = 12;
const round = (value: number): number => Number(value.toFixed(DECIMALS));
const objectValue = (value: unknown, name: string): Record<string, any> => {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
  return value as Record<string, any>;
};
const listValue = (value: unknown, name: string): any[] => {
  if (!Array.isArray(value) || value.length === 0) throw new TypeError(`${name} must be a non-empty list`);
  return value;
};
const textValue = (value: unknown, name: string): string => {
  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
  return value;
};
const numberValue = (value: unknown, name: string): number => {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be finite`);
  return value;
};
const positive = (value: unknown, name: string): number => {
  const result = numberValue(value, name); if (result <= 0) throw new RangeError(`${name} must be positive`); return result;
};
const rate = (value: unknown, name: string): number => {
  const result = numberValue(value, name); if (result < 0 || result >= 1) throw new RangeError(`${name} must be in [0, 1)`); return result;
};
const instant = (value: unknown, name: string): number => {
  const text = textValue(value, name);
  if (!/(Z|[+-]\d{2}:\d{2})$/.test(text)) throw new RangeError(`${name} must include a UTC offset`);
  const result = Date.parse(text); if (!Number.isFinite(result)) throw new RangeError(`${name} must be an ISO 8601 instant`); return result;
};
const dateValue = (value: unknown, name: string): string => {
  const text = textValue(value, name);
  const parsed = new Date(`${text}T00:00:00Z`);
  if (!/^\d{4}-\d{2}-\d{2}$/.test(text) || Number.isNaN(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== text) throw new RangeError(`${name} must use YYYY-MM-DD`);
  return text;
};
const currency = (value: unknown, name: string): string => {
  const text = textValue(value, name); if (!/^[A-Z]{3}$/.test(text)) throw new RangeError(`${name} must be an uppercase three-letter currency code`); return text;
};
const revisionValue = (value: unknown): number => {
  if (!Number.isInteger(value) || (value as number) < 1) throw new RangeError("revision must be a positive integer"); return value as number;
};

export function calculate(data: unknown): Record<string, any> {
  const payload = objectValue(data, "data");
  const asOfText = textValue(payload.asOf, "asOf");
  const asOf = instant(asOfText, "asOf");
  const variant = textValue(payload.returnVariant, "returnVariant");
  if (!new Set(["gross", "net"]).has(variant)) throw new RangeError("returnVariant must be gross or net");
  const priceCurrency = currency(payload.priceCurrency, "priceCurrency");
  if (payload.anchorBasis !== "latest_raw_close") throw new RangeError("anchorBasis must be latest_raw_close");
  const specialPolicy = payload.specialDistributionPolicy;
  if (!new Set(["include_as_cash", "exclude"]).has(specialPolicy)) throw new RangeError("specialDistributionPolicy must be include_as_cash or exclude");

  const observations: any[] = [];
  const seenDates = new Set<string>();
  for (const raw of listValue(payload.observations, "observations")) {
    const row = objectValue(raw, "observation");
    const rowDate = dateValue(row.date, "observation.date");
    if (seenDates.has(rowDate)) throw new RangeError("observation dates must be unique");
    if (observations.length && rowDate <= observations.at(-1).date) throw new RangeError("observations must be strictly ordered by date");
    const availableAt = textValue(row.availableAt, "observation.availableAt");
    if (instant(availableAt, "observation.availableAt") > asOf) throw new RangeError("an observation is unavailable as of asOf");
    observations.push({ date: rowDate, close: positive(row.close, "observation.close"), availableAt });
    seenDates.add(rowDate);
  }
  if (observations.length < 2) throw new RangeError("at least two observations are required");
  const dateToIndex = new Map(observations.map((row, index) => [row.date, index]));

  const grouped = new Map<string, any[]>();
  for (const raw of listValue(payload.eventRevisions, "eventRevisions")) {
    const row = objectValue(raw, "eventRevision");
    const eventId = textValue(row.eventId, "eventId");
    const revision = revisionValue(row.revision);
    const status = textValue(row.status, "status");
    if (!new Set(["confirmed", "cancelled"]).has(status)) throw new RangeError("status must be confirmed or cancelled");
    const classification = textValue(row.classification, "classification");
    if (!new Set(["ordinary", "special"]).has(classification)) throw new RangeError("classification must be ordinary or special");
    const dividendCurrency = currency(row.dividendCurrency, "dividendCurrency");
    const fxRate = positive(row.fxRateToPriceCurrency, "fxRateToPriceCurrency");
    const fxObservedAt = row.fxObservedAt;
    let fxInstant: number | null = null;
    if (dividendCurrency === priceCurrency) {
      if (fxRate !== 1 || fxObservedAt !== null) throw new RangeError("same-currency dividends require FX=1 and fxObservedAt=null");
    } else if (fxObservedAt === null || fxObservedAt === undefined) {
      throw new RangeError("cross-currency FX must have an observation timestamp");
    } else {
      fxInstant = instant(fxObservedAt, "fxObservedAt");
    }
    const availableAt = textValue(row.availableAt, "event.availableAt");
    const availableInstant = instant(availableAt, "event.availableAt");
    const normalized = {
      eventId, revision, status, classification,
      exDate: dateValue(row.exDate, "exDate"),
      grossDividend: positive(row.grossDividend, "grossDividend"),
      dividendCurrency,
      withholdingRate: rate(row.withholdingRate, "withholdingRate"),
      fxRateToPriceCurrency: fxRate,
      fxObservedAt,
      fxInstant,
      availableAt,
      availableInstant,
      sourceId: textValue(row.sourceId, "sourceId"),
    };
    grouped.set(eventId, [...(grouped.get(eventId) ?? []), normalized]);
  }

  const selected: any[] = [];
  const excludedEvents: any[] = [];
  for (const eventId of [...grouped.keys()].sort()) {
    const revisions = grouped.get(eventId)!.sort((a, b) => a.revision - b.revision);
    if (new Set(revisions.map(row => row.revision)).size !== revisions.length) throw new RangeError(`duplicate revision for ${eventId}`);
    for (let index = 1; index < revisions.length; index++) if (revisions[index].availableInstant < revisions[index - 1].availableInstant) throw new RangeError(`revision availability regresses for ${eventId}`);
    const available = revisions.filter(row => row.availableInstant <= asOf);
    if (!available.length) { excludedEvents.push({ eventId, reason: "unavailable_as_of" }); continue; }
    const current = available.at(-1);
    if (current.status === "cancelled") { excludedEvents.push({ eventId, selectedRevision: current.revision, reason: "cancelled" }); continue; }
    if (current.classification === "special" && specialPolicy === "exclude") { excludedEvents.push({ eventId, selectedRevision: current.revision, reason: "special_excluded_by_policy" }); continue; }
    if (current.fxInstant !== null && current.fxInstant > asOf) throw new RangeError(`cross-currency FX for ${eventId} is unavailable as of asOf`);
    if (!dateToIndex.has(current.exDate)) throw new RangeError(`exDate for ${eventId} is absent from observations`);
    const exIndex = dateToIndex.get(current.exDate)!;
    if (exIndex === 0) throw new RangeError(`exDate for ${eventId} needs a prior close`);
    const grossConverted = current.grossDividend * current.fxRateToPriceCurrency;
    let effectiveDividend = grossConverted;
    if (variant === "net") effectiveDividend *= 1 - current.withholdingRate;
    selected.push({ ...current, exIndex, grossConverted, effectiveDividend });
  }

  const byIndex = new Map<number, any[]>();
  for (const event of selected) byIndex.set(event.exIndex, [...(byIndex.get(event.exIndex) ?? []), event]);
  const eventAdjustments: any[] = [];
  const factors = new Map<number, number>();
  const dividendByIndex = new Map<number, number>();
  for (const exIndex of [...byIndex.keys()].sort((a, b) => a - b)) {
    const events = byIndex.get(exIndex)!.sort((a, b) => a.eventId.localeCompare(b.eventId));
    const grossDividend = events.reduce((sum, row) => sum + row.grossConverted, 0);
    const dividend = events.reduce((sum, row) => sum + row.effectiveDividend, 0);
    const priorClose = observations[exIndex - 1].close;
    const exDateClose = observations[exIndex].close;
    if (grossDividend >= priorClose) throw new RangeError("gross converted dividend must be below the chosen pre-event close");
    const factor = exDateClose / (exDateClose + dividend);
    if (!Number.isFinite(factor) || factor <= 0 || factor > 1) throw new RangeError("event factor is undefined");
    factors.set(exIndex, factor); dividendByIndex.set(exIndex, dividend);
    eventAdjustments.push({
      exDate: observations[exIndex].date, exIndex,
      eventIds: events.map(row => row.eventId), selectedRevisions: events.map(row => row.revision), sourceIds: events.map(row => row.sourceId),
      priorClose: round(priorClose), exDateClose: round(exDateClose), grossDividendPriceCurrency: round(grossDividend), effectiveDividend: round(dividend), backwardFactor: round(factor),
      factorAppliesTo: `indices < ${exIndex}`,
    });
  }

  let running = 1;
  const cumulativeFactors = Array(observations.length).fill(1);
  const adjustedPrices = Array(observations.length).fill(0);
  for (let index = observations.length - 1; index >= 0; index--) {
    cumulativeFactors[index] = running;
    adjustedPrices[index] = observations[index].close * running;
    if (factors.has(index)) running *= factors.get(index)!;
  }
  const returnLinks = [];
  for (let index = 1; index < observations.length; index++) {
    const previous = observations[index - 1].close;
    const current = observations[index].close;
    const dividend = dividendByIndex.get(index) ?? 0;
    returnLinks.push({ date: observations[index].date, priceReturn: round(current / previous - 1), totalReturn: round((current + dividend) / previous - 1), effectiveDividend: round(dividend) });
  }
  return {
    methodology: "backward_adjusted_ex_date_close_total_return", returnVariant: variant, priceCurrency, asOf: asOfText,
    anchor: { basis: "latest_raw_close", date: observations.at(-1).date, rawClose: round(observations.at(-1).close) },
    adjustedPrices: adjustedPrices.map(round), cumulativeFactors: cumulativeFactors.map(round), eventAdjustments, returnLinks, excludedEvents,
    rounding: { internal: "unrounded IEEE-754 binary64", serializedDecimalPlaces: DECIMALS, factorCompounding: "multiply unrounded factors, round only serialized output" },
  };
}