Survivorship-Bias Guard: Keep Historical Failures in the Test

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

/** Bitemporal survivorship-bias guard for D02-F04-A02. */

type Mapping = Record<string, unknown>;
type State = "eligible" | "ineligible" | "unknown" | "ambiguous";

const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;

function mapping(value: unknown, name: string): Mapping {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be a mapping`);
  return value as Mapping;
}
function textValue(value: unknown, name: string): string {
  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
  return value;
}
function instant(value: unknown, name: string): number {
  const stringValue = textValue(value, name);
  if (!UTC.test(stringValue)) throw new Error(`${name} must be a strict UTC instant YYYY-MM-DDTHH:mm:ssZ`);
  const parsed = Date.parse(stringValue);
  if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== stringValue.replace("Z", ".000Z")) throw new Error(`${name} is not a calendar-valid instant`);
  return parsed;
}
function positiveInt(value: unknown, name: string): number {
  if (!Number.isInteger(value) || (value as number) < 1) throw new TypeError(`${name} must be a positive integer`);
  return value as number;
}
function uniqueTexts(value: unknown, name: string, allowEmpty = false): string[] {
  if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) throw new TypeError(`${name} must be ${allowEmpty ? "a" : "a non-empty"} list`);
  const checked = value.map((item) => textValue(item, `${name}[]`));
  if (new Set(checked).size !== checked.length) throw new Error(`${name} must not contain duplicates`);
  return checked;
}
function contains(moment: number, start: number, end: number | null): boolean {
  return start <= moment && (end === null || moment < end);
}
function clone<T>(value: T): T { return JSON.parse(JSON.stringify(value)) as T; }
function causallyAvailableRows(raw: unknown, name: string, known: number, requireNonempty: boolean): Mapping[] {
  if (!Array.isArray(raw) || (requireNonempty && raw.length === 0)) throw new TypeError(`${name} must be ${requireNonempty ? "a non-empty" : "a"} list`);
  return raw.map((item, i) => mapping(item, `${name}[${i}]`)).filter((row, i) => instant(row.availableAt, `${name}[${i}].availableAt`) <= known);
}

type Definition = {
  definitionId: string; universeId: string; revision: number; effectiveFrom: string;
  effectiveStart: number; effectiveTo: string | null; effectiveEnd: number | null;
  announcedAt: string; availableAt: string; availableInstant: number; status: string;
  baseType: string; baseId: string; ruleSummary: string; sourceId: string;
};
type Membership = {
  membershipId: string; revision: number; universeId: string; securityId: string;
  validFrom: string; validStart: number; validTo: string | null; validEnd: number | null;
  announcedAt: string; availableAt: string; availableInstant: number; status: string;
  changeType: string; eventId: string; sourceId: string;
};

function validateDefinitions(raw: unknown, universeId: string, definitionId: string): Definition[] {
  if (!Array.isArray(raw)) throw new TypeError("universeDefinitions must be a list");
  const definitions = raw.map((item, i) => {
    const row = mapping(item, `universeDefinitions[${i}]`); const p = `universeDefinitions[${i}]`;
    const status = textValue(row.status, `${p}.status`);
    if (!new Set(["active", "cancelled"]).has(status)) throw new Error(`${p}.status must be active or cancelled`);
    const announcedAt = textValue(row.announcedAt, `${p}.announcedAt`); const announced = instant(announcedAt, `${p}.announcedAt`);
    const availableAt = textValue(row.availableAt, `${p}.availableAt`); const availableInstant = instant(availableAt, `${p}.availableAt`);
    if (availableInstant < announced) throw new Error(`${p}.availableAt cannot precede announcedAt`);
    const effectiveFrom = textValue(row.effectiveFrom, `${p}.effectiveFrom`); const effectiveStart = instant(effectiveFrom, `${p}.effectiveFrom`);
    const effectiveTo = row.effectiveTo === null ? null : textValue(row.effectiveTo, `${p}.effectiveTo`);
    const effectiveEnd = effectiveTo === null ? null : instant(effectiveTo, `${p}.effectiveTo`);
    if (effectiveEnd !== null && effectiveEnd <= effectiveStart) throw new Error(`${p}.effectiveTo must be after effectiveFrom`);
    const result: Definition = {
      definitionId: textValue(row.definitionId, `${p}.definitionId`), universeId: textValue(row.universeId, `${p}.universeId`),
      revision: positiveInt(row.revision, `${p}.revision`), effectiveFrom, effectiveStart, effectiveTo, effectiveEnd,
      announcedAt, availableAt, availableInstant, status, baseType: textValue(row.baseType, `${p}.baseType`),
      baseId: textValue(row.baseId, `${p}.baseId`), ruleSummary: textValue(row.ruleSummary, `${p}.ruleSummary`), sourceId: textValue(row.sourceId, `${p}.sourceId`),
    };
    if (result.universeId !== universeId || result.definitionId !== definitionId) throw new Error(`${p} does not match the requested universe and definition`);
    return result;
  });
  if (definitions.length === 0) return [];
  const ordered = [...definitions].sort((a, b) => a.revision - b.revision);
  if (ordered.some((row, i) => row.revision !== i + 1)) throw new Error("universe definition revisions must be contiguous from 1");
  const immutable = new Set(ordered.map((row) => [row.universeId, row.definitionId, row.baseType, row.baseId, row.effectiveFrom].join("\u0000")));
  if (immutable.size !== 1) throw new Error("universe definition revisions change immutable identity fields");
  if (ordered.some((row, i) => i > 0 && row.availableInstant <= ordered[i - 1].availableInstant)) throw new Error("universe definition availability must increase with revision");
  return definitions;
}

function validateMemberships(raw: unknown, universeId: string): Membership[] {
  if (!Array.isArray(raw)) throw new TypeError("membershipRecords must be a list");
  const records = raw.map((item, i) => {
    const row = mapping(item, `membershipRecords[${i}]`); const p = `membershipRecords[${i}]`;
    const status = textValue(row.status, `${p}.status`); const changeType = textValue(row.changeType, `${p}.changeType`);
    if (!new Set(["active", "cancelled"]).has(status)) throw new Error(`${p}.status must be active or cancelled`);
    if (!new Set(["entry", "exit", "revision", "cancellation"]).has(changeType)) throw new Error(`${p}.changeType is unsupported`);
    if ((status === "cancelled") !== (changeType === "cancellation")) throw new Error(`${p} cancellation status and changeType must agree`);
    const announcedAt = textValue(row.announcedAt, `${p}.announcedAt`); const announced = instant(announcedAt, `${p}.announcedAt`);
    const availableAt = textValue(row.availableAt, `${p}.availableAt`); const availableInstant = instant(availableAt, `${p}.availableAt`);
    if (availableInstant < announced) throw new Error(`${p}.availableAt cannot precede announcedAt`);
    const validFrom = textValue(row.validFrom, `${p}.validFrom`); const validStart = instant(validFrom, `${p}.validFrom`);
    const validTo = row.validTo === null ? null : textValue(row.validTo, `${p}.validTo`); const validEnd = validTo === null ? null : instant(validTo, `${p}.validTo`);
    if (validEnd !== null && validEnd <= validStart) throw new Error(`${p}.validTo must be after validFrom`);
    const result: Membership = {
      membershipId: textValue(row.membershipId, `${p}.membershipId`), revision: positiveInt(row.revision, `${p}.revision`),
      universeId: textValue(row.universeId, `${p}.universeId`), securityId: textValue(row.securityId, `${p}.securityId`),
      validFrom, validStart, validTo, validEnd, announcedAt, availableAt, availableInstant, status, changeType,
      eventId: textValue(row.eventId, `${p}.eventId`), sourceId: textValue(row.sourceId, `${p}.sourceId`),
    };
    if (result.universeId !== universeId) throw new Error(`${p}.universeId does not match universeId`);
    return result;
  });
  for (const membershipId of [...new Set(records.map((row) => row.membershipId))]) {
    const ordered = records.filter((row) => row.membershipId === membershipId).sort((a, b) => a.revision - b.revision);
    if (ordered.some((row, i) => row.revision !== i + 1)) throw new Error(`membership ${membershipId} revisions must be contiguous from 1`);
    const immutable = new Set(ordered.map((row) => [row.universeId, row.securityId, row.validFrom].join("\u0000")));
    if (immutable.size !== 1) throw new Error(`membership ${membershipId} changes immutable identity fields`);
    if (ordered.some((row, i) => i > 0 && row.availableInstant <= ordered[i - 1].availableInstant)) throw new Error(`membership ${membershipId} availability must increase with revision`);
  }
  return records;
}

function emptyResult(universeId: string, definitionId: string, effectiveAt: string, knownAt: string, status: string, diagnostic: string): Mapping {
  return {status, universeId, definitionId, definitionVersion: null, effectiveAt, knownAt, classifications: [], eligibleSecurityIds: [], ineligibleSecurityIds: [], unknownSecurityIds: [], ambiguousSecurityIds: [], membershipEventVersionsUsed: [], diagnostics: [diagnostic], hindsightDiagnostics: null};
}

export function guardSurvivorship(input: unknown): Mapping {
  const data = mapping(input, "data");
  const universeId = textValue(data.universeId, "universeId"); const definitionId = textValue(data.definitionId, "definitionId");
  const effectiveAt = textValue(data.effectiveAt, "effectiveAt"); const effective = instant(effectiveAt, "effectiveAt");
  const knownAt = textValue(data.knownAt, "knownAt"); const known = instant(knownAt, "knownAt");
  const definitions = validateDefinitions(causallyAvailableRows(data.universeDefinitions, "universeDefinitions", known, true), universeId, definitionId);
  const records = validateMemberships(causallyAvailableRows(data.membershipRecords, "membershipRecords", known, false), universeId);
  if (definitions.length === 0) return emptyResult(universeId, definitionId, effectiveAt, knownAt, "unknown", "no universe definition was available by knownAt");
  const definition = definitions.sort((a, b) => b.revision - a.revision)[0];
  if (definition.status === "cancelled" || !contains(effective, definition.effectiveStart, definition.effectiveEnd)) return emptyResult(universeId, definitionId, effectiveAt, knownAt, "unknown", "the selected universe definition was cancelled or not effective at effectiveAt");
  if (definition.baseType !== "named_research_universe") return emptyResult(universeId, definitionId, effectiveAt, knownAt, "unsupported", `unsupported baseType: ${definition.baseType}`);
  const candidateUniverse = mapping(data.candidateUniverse, "candidateUniverse");
  const construction = textValue(candidateUniverse.construction, "candidateUniverse.construction");
  if (construction !== "historical_membership_ledger") return emptyResult(universeId, definitionId, effectiveAt, knownAt, "unsupported", `unsupported candidate-universe construction: ${construction}`);
  const candidateAsOf = textValue(candidateUniverse.asOf, "candidateUniverse.asOf"); const candidateAsOfInstant = instant(candidateAsOf, "candidateUniverse.asOf");
  const candidateAvailableAt = textValue(candidateUniverse.availableAt, "candidateUniverse.availableAt"); const candidateAvailableInstant = instant(candidateAvailableAt, "candidateUniverse.availableAt");
  if (candidateAsOfInstant > candidateAvailableInstant) throw new Error("candidateUniverse.asOf cannot follow candidateUniverse.availableAt");
  if (candidateAvailableInstant > known) return emptyResult(universeId, definitionId, effectiveAt, knownAt, "incomplete", "candidate universe was not available by knownAt");
  const candidateSourceId = textValue(candidateUniverse.sourceId, "candidateUniverse.sourceId");
  const candidates = uniqueTexts(candidateUniverse.securityIds, "candidateUniverse.securityIds");
  const selected: Membership[] = [];
  for (const membershipId of [...new Set(records.map((row) => row.membershipId))].sort()) {
    const eligibleVersions = records.filter((row) => row.membershipId === membershipId).sort((a, b) => b.revision - a.revision);
    if (eligibleVersions.length) selected.push(eligibleVersions[0]);
  }
  const knownLedgerIds = new Set(selected.map((row) => row.securityId)); const candidateSet = new Set(candidates);
  const omittedKnownIds = [...knownLedgerIds].filter((id) => !candidateSet.has(id)).sort();
  if (omittedKnownIds.length) {
    const incomplete = emptyResult(universeId, definitionId, effectiveAt, knownAt, "incomplete", "candidate universe omits identities present in the known membership ledger");
    incomplete.candidateUniverseSourceId = candidateSourceId; incomplete.omittedKnownSecurityIds = omittedKnownIds; return incomplete;
  }
  const usedVersions = new Set<string>();
  const classifications = [...candidates].sort().map((securityId) => {
    const securityRecords = selected.filter((row) => row.securityId === securityId); const active = securityRecords.filter((row) => row.status === "active");
    const covering = active.filter((row) => contains(effective, row.validStart, row.validEnd));
    securityRecords.forEach((row) => usedVersions.add(`${row.membershipId}@${row.revision}`));
    let state: State; let diagnostic: string; let evidenceVersions: string[];
    if (covering.length === 1) { state = "eligible"; diagnostic = "one known active membership interval covers effectiveAt"; evidenceVersions = [`${covering[0].membershipId}@${covering[0].revision}`]; }
    else if (covering.length > 1) { state = "ambiguous"; diagnostic = "multiple known active membership intervals cover effectiveAt"; evidenceVersions = covering.map((row) => `${row.membershipId}@${row.revision}`).sort(); }
    else if (active.length) { state = "ineligible"; diagnostic = "known active membership evidence excludes effectiveAt"; evidenceVersions = active.map((row) => `${row.membershipId}@${row.revision}`).sort(); }
    else { state = "unknown"; diagnostic = "no non-cancelled membership evidence was available by knownAt"; evidenceVersions = securityRecords.map((row) => `${row.membershipId}@${row.revision}`).sort(); }
    return {securityId, state, evidenceVersions, diagnostic};
  });
  const byState = Object.fromEntries((["eligible", "ineligible", "unknown", "ambiguous"] as State[]).map((state) => [state, classifications.filter((row) => row.state === state).map((row) => row.securityId)])) as Record<State, string[]>;
  const status = byState.ambiguous.length ? "ambiguous" : (byState.unknown.length ? "unknown" : "resolved");
  const result: Mapping = {status, universeId, definitionId, definitionVersion: `${definitionId}@${definition.revision}`, effectiveAt, knownAt, candidateUniverseSourceId: candidateSourceId, candidateUniverseAsOf: candidateAsOf, classifications,
    eligibleSecurityIds: byState.eligible, ineligibleSecurityIds: byState.ineligible, unknownSecurityIds: byState.unknown, ambiguousSecurityIds: byState.ambiguous,
    membershipEventVersionsUsed: [...usedVersions].sort(), diagnostics: [], hindsightDiagnostics: null};
  if (data.comparisonRoster !== undefined && data.comparisonRoster !== null) {
    const comparison = mapping(data.comparisonRoster, "comparisonRoster");
    const observedAt = textValue(comparison.observedAt, "comparisonRoster.observedAt"); instant(observedAt, "comparisonRoster.observedAt");
    const availableAt = textValue(comparison.availableAt, "comparisonRoster.availableAt"); const comparisonAvailable = instant(availableAt, "comparisonRoster.availableAt");
    if (instant(observedAt, "comparisonRoster.observedAt") > comparisonAvailable) throw new Error("comparisonRoster.observedAt cannot follow comparisonRoster.availableAt");
    const roster = uniqueTexts(comparison.securityIds, "comparisonRoster.securityIds", true).sort(); const sourceId = textValue(comparison.sourceId, "comparisonRoster.sourceId");
    const historical = new Set(byState.eligible); const current = new Set(roster); const retained = [...historical].filter((id) => current.has(id)).sort();
    result.hindsightDiagnostics = {causal: false, doesNotAlterCausalResult: true, observedAt, availableAt, sourceId, currentRosterSecurityIds: roster,
      historicallyEligibleMissingFromCurrent: [...historical].filter((id) => !current.has(id)).sort(), currentRosterNotHistoricallyEligible: [...current].filter((id) => !historical.has(id)).sort(),
      retainedHistoricalCount: retained.length, historicallyEligibleCount: historical.size, retentionRatio: historical.size ? Number((retained.length / historical.size).toFixed(6)) : null};
  }
  return clone(result);
}

export function compareEqualWeightedReturns(guardResultInput: unknown, returnRowsInput: unknown): Mapping {
  const guardResult = mapping(guardResultInput, "guard_result");
  if (guardResult.status !== "resolved") throw new Error("guard_result must be resolved");
  const hindsight = mapping(guardResult.hindsightDiagnostics, "hindsightDiagnostics");
  if (!Array.isArray(returnRowsInput)) throw new TypeError("return_rows must be a list");
  const values = new Map<string, number>();
  const periods = new Set<string>(); const guardKnown = instant(guardResult.knownAt, "guard_result.knownAt");
  returnRowsInput.forEach((item, i) => {
    const row = mapping(item, `return_rows[${i}]`); const securityId = textValue(row.securityId, `return_rows[${i}].securityId`); const value = row.simpleReturn;
    if (row.isSynthetic !== true) throw new Error(`return_rows[${i}].isSynthetic must be true; this comparator is synthetic-only`);
    if (textValue(row.observationStatus, `return_rows[${i}].observationStatus`) !== "observed") throw new Error(`return_rows[${i}].observationStatus must be observed`);
    if (textValue(row.outcomeBasis, `return_rows[${i}].outcomeBasis`) !== "complete_period_simple_return") throw new Error(`return_rows[${i}].outcomeBasis is unsupported`);
    const periodStart = textValue(row.periodStart, `return_rows[${i}].periodStart`); const start = instant(periodStart, `return_rows[${i}].periodStart`);
    const periodEnd = textValue(row.periodEnd, `return_rows[${i}].periodEnd`); const end = instant(periodEnd, `return_rows[${i}].periodEnd`);
    const available = instant(row.availableAt, `return_rows[${i}].availableAt`); textValue(row.sourceId, `return_rows[${i}].sourceId`);
    if (end <= start || available < end) throw new Error(`return_rows[${i}] has an invalid period or availability order`);
    if (available > guardKnown) throw new Error(`return_rows[${i}] was unavailable by guard_result.knownAt`);
    periods.add(`${periodStart}\u0000${periodEnd}`);
    if (typeof value !== "number" || !Number.isFinite(value) || value < -1) throw new Error(`return_rows[${i}].simpleReturn must be finite and at least -1`);
    if (values.has(securityId)) throw new Error("return_rows must not contain duplicate securityId values"); values.set(securityId, value);
  });
  if (periods.size > 1) throw new Error("return_rows must use one common period");
  const historicalIds = guardResult.eligibleSecurityIds as string[]; const currentSet = new Set(hindsight.currentRosterSecurityIds as string[]);
  const retainedIds = historicalIds.filter((id) => currentSet.has(id)); const missing = historicalIds.filter((id) => !values.has(id)).sort();
  if (missing.length) return {status: "missing_returns", missingReturnSecurityIds: missing};
  if (!retainedIds.length) return {status: "empty_current_subset", missingReturnSecurityIds: []};
  const historicalMean = historicalIds.reduce((sum, id) => sum + values.get(id)!, 0) / historicalIds.length;
  const currentOnlyMean = retainedIds.reduce((sum, id) => sum + values.get(id)!, 0) / retainedIds.length;
  return {status: "calculated", historicalEligibleSecurityIds: historicalIds, currentRosterSubsetSecurityIds: retainedIds,
    historicalEqualWeightedReturn: Number(historicalMean.toFixed(6)), currentRosterSubsetEqualWeightedReturn: Number(currentOnlyMean.toFixed(6)),
    signedDifference: Number((currentOnlyMean - historicalMean).toFixed(6)), interpretation: "synthetic case only; sign and magnitude are not universal",
    terminalOutcomePolicy: "no reconstruction or imputation; supplied synthetic rows assert complete period outcomes"};
}

export const calculate = guardSurvivorship;