CRSP Cumulative Price Adjustment: Respect the Vendor Basis, Sign, and Gaps

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

/** Archived CRSPAccess cumulative-price adjustment teaching reference. */

export const CRSP_CONVENTION = "CRSPAccess-ts_print-cumfacpr-archived" as const;
export const CRSP_GAP_POLICY = "stop-at-unknown-exchange" as const;

type CoverageStatus = "observed" | "unknown_exchange_gap" | "post_delisting_unpriced";
type CrspPriceKind = "trade" | "bid_ask_average" | "missing";

export interface CrspFactorEvent {
  crspExdt: string;
  crspFacpr: number;
  syntheticLabel: string;
}

export interface CrspPriceRecord {
  date: string;
  crspPrc: number | null;
  crspCumfacpr: number | null;
  crspPriceKind: CrspPriceKind;
  coverageStatus: CoverageStatus;
}

export interface CrspAdjustmentInput {
  crspConvention: typeof CRSP_CONVENTION;
  crspSourceVersion: string;
  packageSecurityKey: `SYNTHETIC-${string}`;
  crspBaseDate: string;
  crspGapPolicy: typeof CRSP_GAP_POLICY;
  roundingDecimals?: number;
  crspFactorEvents: CrspFactorEvent[];
  records: CrspPriceRecord[];
}

type JsonObject = Record<string, unknown>;
const COVERAGE = new Set<CoverageStatus>(["observed", "unknown_exchange_gap", "post_delisting_unpriced"]);
const PRICE_KINDS = new Set<CrspPriceKind>(["trade", "bid_ask_average", "missing"]);

function objectValue(value: unknown, name: string): JsonObject {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
  return value as JsonObject;
}

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

function isoDate(value: unknown, name: string): string {
  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new TypeError(`${name} must be YYYY-MM-DD`);
  const parsed = new Date(`${value}T00:00:00Z`);
  if (Number.isNaN(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== value) throw new RangeError(`${name} must be a real ISO date`);
  return value;
}

function roundHalfAway(value: number, decimals: number): number {
  const scale = 10 ** decimals;
  const scaled = value * scale;
  const rounded = scaled >= 0 ? Math.floor(scaled + 0.5) : Math.ceil(scaled - 0.5);
  return rounded / scale;
}

function validateEvent(value: unknown, index: number): CrspFactorEvent {
  const item = objectValue(value, `crspFactorEvents[${index}]`);
  const crspExdt = isoDate(item.crspExdt, `crspFactorEvents[${index}].crspExdt`);
  const crspFacpr = numberValue(item.crspFacpr, `crspFactorEvents[${index}].crspFacpr`);
  if (typeof item.syntheticLabel !== "string" || !item.syntheticLabel.trim()) throw new TypeError(`crspFactorEvents[${index}].syntheticLabel must be non-empty`);
  return { crspExdt, crspFacpr, syntheticLabel: item.syntheticLabel };
}

export function calculate(input: CrspAdjustmentInput | unknown) {
  const source = objectValue(input, "data");
  if (source.crspConvention !== CRSP_CONVENTION) throw new RangeError(`crspConvention must equal ${CRSP_CONVENTION}`);
  if (source.crspGapPolicy !== CRSP_GAP_POLICY) throw new RangeError(`crspGapPolicy must equal ${CRSP_GAP_POLICY}`);
  if (typeof source.crspSourceVersion !== "string" || !source.crspSourceVersion.trim()) throw new TypeError("crspSourceVersion must be non-empty");
  if (typeof source.packageSecurityKey !== "string" || !source.packageSecurityKey.startsWith("SYNTHETIC-")) throw new RangeError("packageSecurityKey must be an unmistakably synthetic identifier");
  const crspBaseDate = isoDate(source.crspBaseDate, "crspBaseDate");
  const decimals = source.roundingDecimals === undefined ? 6 : source.roundingDecimals;
  if (!Number.isInteger(decimals) || (decimals as number) < 0 || (decimals as number) > 12) throw new RangeError("roundingDecimals must be an integer from 0 through 12");
  if (!Array.isArray(source.crspFactorEvents)) throw new TypeError("crspFactorEvents must be a list");
  const events = source.crspFactorEvents.map(validateEvent);
  const eventDates = events.map((event) => event.crspExdt);
  if (eventDates.some((value, index) => index > 0 && value < eventDates[index - 1])) throw new RangeError("crspFactorEvents must be ordered by crspExdt");
  if (!Array.isArray(source.records) || source.records.length === 0) throw new TypeError("records must be a non-empty list");

  const outputRecords: JsonObject[] = [];
  const dates: string[] = [];
  const factorChangeDates: string[] = [];
  let baseFactorSeen = false;
  let priorFactor: number | null = null;

  source.records.forEach((rawRecord, index) => {
    const record = objectValue(rawRecord, `records[${index}]`);
    const recordDate = isoDate(record.date, `records[${index}].date`);
    if (dates.length && recordDate <= dates[dates.length - 1]) throw new RangeError("records must have unique, strictly increasing dates");
    dates.push(recordDate);
    if (!COVERAGE.has(record.coverageStatus as CoverageStatus)) throw new RangeError(`records[${index}].coverageStatus is unsupported`);
    if (!PRICE_KINDS.has(record.crspPriceKind as CrspPriceKind)) throw new RangeError(`records[${index}].crspPriceKind is unsupported`);
    const coverage = record.coverageStatus as CoverageStatus;
    const priceKind = record.crspPriceKind as CrspPriceKind;
    let adjusted: number | null;
    let magnitude: number | null;
    let recovered: number | null;
    let status: string;

    if (coverage !== "observed") {
      if (record.crspCumfacpr !== null) throw new RangeError("coverage gaps require null crspCumfacpr");
      if (coverage === "post_delisting_unpriced" && (record.crspPrc !== null || priceKind !== "missing")) throw new RangeError("an unpriced CRSP delisting requires null crspPrc and missing crspPriceKind");
      if (coverage === "unknown_exchange_gap" && record.crspPrc === null && priceKind !== "missing") throw new RangeError("a null CRSP gap price requires missing crspPriceKind");
      if (coverage === "unknown_exchange_gap" && record.crspPrc !== null) {
        const gapPrice = numberValue(record.crspPrc, `records[${index}].crspPrc`);
        if (priceKind === "trade" && gapPrice <= 0) throw new RangeError("CRSP trade prc must be positive");
        if (priceKind === "bid_ask_average" && gapPrice >= 0) throw new RangeError("CRSP bid/ask-average prc must retain its negative sign marker");
        if (priceKind === "missing" && gapPrice !== 0) throw new RangeError("archived CRSPAccess missing prc must be zero");
      }
      status = coverage === "unknown_exchange_gap" ? "CRSP_FACTOR_GAP" : "CRSP_POST_DELISTING_UNPRICED";
      adjusted = magnitude = recovered = null;
    } else {
      const price = numberValue(record.crspPrc, `records[${index}].crspPrc`);
      const factor = numberValue(record.crspCumfacpr, `records[${index}].crspCumfacpr`);
      if (factor <= 0) throw new RangeError("observed CRSP cumfacpr must be positive");
      if (priceKind === "trade" && price <= 0) throw new RangeError("CRSP trade prc must be positive");
      if (priceKind === "bid_ask_average" && price >= 0) throw new RangeError("CRSP bid/ask-average prc must retain its negative sign marker");
      if (priceKind === "missing" && price !== 0) throw new RangeError("archived CRSPAccess missing prc must be zero");
      if (priceKind !== "missing" && price === 0) throw new RangeError("zero CRSP prc must be labeled missing");
      if (recordDate === crspBaseDate) {
        if (factor !== 1) throw new RangeError("CRSP base-date cumfacpr must equal 1.0");
        baseFactorSeen = true;
      }
      if (priorFactor !== null && factor !== priorFactor) factorChangeDates.push(recordDate);
      priorFactor = factor;
      if (priceKind === "missing") {
        status = "CRSP_PRICE_MISSING";
        adjusted = magnitude = recovered = null;
      } else {
        const unrounded = price * factor;
        adjusted = roundHalfAway(unrounded, decimals as number);
        magnitude = roundHalfAway(Math.abs(unrounded), decimals as number);
        recovered = roundHalfAway(adjusted / factor, decimals as number);
        status = priceKind === "trade" ? "CRSP_ADJUSTED_TRADE" : "CRSP_ADJUSTED_BID_ASK_AVERAGE";
      }
    }
    outputRecords.push({
      date: recordDate,
      crspPrc: record.crspPrc,
      crspCumfacpr: record.crspCumfacpr,
      crspAdjustedPrice: adjusted,
      crspAdjustedMagnitude: magnitude,
      crspRecoveredPrc: recovered,
      crspPriceKind: priceKind,
      coverageStatus: coverage,
      status,
    });
  });

  if (!baseFactorSeen) throw new RangeError("records must contain an observed CRSP base-date row with cumfacpr 1.0");
  if (events.some((event) => event.crspExdt < dates[0] || event.crspExdt > dates[dates.length - 1])) throw new RangeError("CRSP factor event dates must fall inside the record range");
  return {
    crspConvention: CRSP_CONVENTION,
    crspSourceVersion: source.crspSourceVersion,
    packageSecurityKey: source.packageSecurityKey,
    crspBaseDate,
    crspGapPolicy: CRSP_GAP_POLICY,
    crspPriceFormula: "CRSP adjusted price = CRSP PRC * CRSP CUMFACPR",
    crspFactorEvents: events,
    crspFactorChangeDates: factorChangeDates,
    roundingDecimals: decimals,
    records: outputRecords,
  };
}