Share-Class Relationship Mapping: Same Issuer Does Not Mean Same Security

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

/** Bitemporal share-class relationship resolver. */
type RecordValue = Record<string, any>;

const ENTITY_TYPES = new Set(["ISSUER", "LEGAL_INSTRUMENT", "SHARE_CLASS", "LISTING", "TRADING_LINE", "VENUE"]);
const RELATIONSHIP_TYPES = new Set([
  "ISSUED_BY", "CLASS_OF", "LISTED_AS", "TRADING_LINE_OF", "TRADES_ON",
  "VOTING_RIGHTS", "ECONOMIC_RIGHTS", "DIVIDEND_PREFERENCE", "CONVERTS_TO",
  "EXCHANGES_TO", "REDEEMABLE_FOR", "PARTICIPATION_RIGHTS", "SENIOR_TO", "FUNGIBLE_WITH",
]);
const RATIO_RELATIONSHIPS = new Set(["VOTING_RIGHTS", "ECONOMIC_RIGHTS", "CONVERTS_TO", "EXCHANGES_TO", "FUNGIBLE_WITH"]);
const ENDPOINTS: Record<string, [Set<string>, Set<string>]> = {
  ISSUED_BY: [new Set(["LEGAL_INSTRUMENT"]), new Set(["ISSUER"])],
  CLASS_OF: [new Set(["SHARE_CLASS"]), new Set(["LEGAL_INSTRUMENT"])],
  LISTED_AS: [new Set(["SHARE_CLASS"]), new Set(["LISTING"])],
  TRADING_LINE_OF: [new Set(["TRADING_LINE"]), new Set(["LISTING"])],
  TRADES_ON: [new Set(["TRADING_LINE"]), new Set(["VENUE"])],
  VOTING_RIGHTS: [new Set(["SHARE_CLASS"]), new Set(["ISSUER"])],
  ECONOMIC_RIGHTS: [new Set(["SHARE_CLASS"]), new Set(["ISSUER", "LEGAL_INSTRUMENT"])],
  DIVIDEND_PREFERENCE: [new Set(["SHARE_CLASS"]), new Set(["ISSUER", "LEGAL_INSTRUMENT"])],
  CONVERTS_TO: [new Set(["SHARE_CLASS"]), new Set(["SHARE_CLASS"])],
  EXCHANGES_TO: [new Set(["SHARE_CLASS"]), new Set(["SHARE_CLASS"])],
  REDEEMABLE_FOR: [new Set(["SHARE_CLASS"]), new Set(["ISSUER", "LEGAL_INSTRUMENT"])],
  PARTICIPATION_RIGHTS: [new Set(["SHARE_CLASS"]), new Set(["ISSUER", "LEGAL_INSTRUMENT"])],
  SENIOR_TO: [new Set(["SHARE_CLASS"]), new Set(["SHARE_CLASS"])],
  FUNGIBLE_WITH: [new Set(["SHARE_CLASS", "TRADING_LINE"]), new Set(["SHARE_CLASS", "TRADING_LINE"])],
};

function text(value: unknown, name: string): string {
  if (typeof value !== "string" || value.trim() === "") throw new RangeError(`${name} must be a non-empty string`);
  return value;
}

function instant(value: unknown, name: string): number {
  const raw = text(value, name);
  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(raw)) throw new RangeError(`${name} must be an RFC 3339 UTC instant ending in Z`);
  const parsed = Date.parse(raw);
  if (!Number.isFinite(parsed)) throw new RangeError(`${name} is not a valid timestamp`);
  const normalized = new Date(parsed).toISOString();
  const expected = raw.includes(".") ? raw.replace(/\.(\d)Z$/, ".$100Z").replace(/\.(\d{2})Z$/, ".$10Z") : raw.replace("Z", ".000Z");
  if (normalized !== expected) throw new RangeError(`${name} is not a valid calendar timestamp`);
  return parsed;
}

function safeInt(value: unknown, name: string, allowZero = false): number {
  if (!Number.isSafeInteger(value) || (allowZero ? Number(value) < 0 : Number(value) <= 0)) {
    throw new RangeError(`${name} must be a ${allowZero ? "non-negative" : "positive"} safe integer`);
  }
  return Number(value);
}

function ratio(terms: unknown, name: string, allowZero: boolean): [number, number, string] {
  if (!terms || typeof terms !== "object" || Array.isArray(terms)) throw new TypeError(`${name}.terms must be an object`);
  const item = terms as RecordValue;
  return [safeInt(item.numerator, `${name}.terms.numerator`, allowZero), safeInt(item.denominator, `${name}.terms.denominator`), text(item.unit, `${name}.terms.unit`)];
}

function validateSource(source: unknown, name: string): void {
  if (!source || typeof source !== "object" || Array.isArray(source)) throw new TypeError(`${name}.source must be an object`);
  const item = source as RecordValue;
  for (const field of ["sourceId", "sourceType", "documentDate", "locator"]) text(item[field], `${name}.source.${field}`);
}

function validateTerms(relation: RecordValue, name: string): void {
  const terms = relation.terms;
  if (!terms || typeof terms !== "object" || Array.isArray(terms)) throw new TypeError(`${name}.terms must be an object`);
  const type = relation.relationshipType;
  if (RATIO_RELATIONSHIPS.has(type)) ratio(terms, name, type === "VOTING_RIGHTS");
  if (["CONVERTS_TO", "EXCHANGES_TO", "FUNGIBLE_WITH"].includes(type)) {
    if (!Array.isArray(terms.conditions) || terms.conditions.some((item: unknown) => typeof item !== "string" || item === "")) throw new RangeError(`${name}.terms.conditions must be a string list`);
  }
  if (type === "FUNGIBLE_WITH" && terms.symmetric !== true) throw new RangeError(`${name}.terms.symmetric must be true`);
  if (type === "DIVIDEND_PREFERENCE") {
    text(terms.currency, `${name}.terms.currency`); safeInt(terms.minorUnits, `${name}.terms.minorUnits`, true); safeInt(terms.perShares, `${name}.terms.perShares`);
    if (typeof terms.cumulative !== "boolean") throw new TypeError(`${name}.terms.cumulative must be boolean`);
  }
  if (type === "REDEEMABLE_FOR") {
    text(terms.currency, `${name}.terms.currency`); safeInt(terms.minorUnits, `${name}.terms.minorUnits`, true); safeInt(terms.perShares, `${name}.terms.perShares`);
    if (typeof terms.holderOption !== "boolean") throw new TypeError(`${name}.terms.holderOption must be boolean`);
  }
  const unsupported = relation.unsupportedTerms ?? [];
  if (!Array.isArray(unsupported) || unsupported.some((item: unknown) => typeof item !== "string" || item === "")) throw new RangeError(`${name}.unsupportedTerms must be a string list`);
}

function gcd(a: bigint, b: bigint): bigint { let left = a < 0n ? -a : a; let right = b < 0n ? -b : b; while (right) [left, right] = [right, left % right]; return left; }
function reduced(numerator: number, denominator: number): { numerator: number; denominator: number } {
  const divisor = gcd(BigInt(numerator), BigInt(denominator));
  const n = BigInt(numerator) / divisor; const d = BigInt(denominator) / divisor;
  if (n > BigInt(Number.MAX_SAFE_INTEGER) || d > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("derived ratio exceeds the safe-integer boundary");
  return { numerator: Number(n), denominator: Number(d) };
}
function divideRatios(left: [number, number, string] | null, right: [number, number, string] | null): RecordValue {
  if (!left || !right) return { status: "NOT_ESTABLISHED" };
  if (left[2] !== right[2]) return { status: "INCOMPARABLE_UNITS", leftUnit: left[2], rightUnit: right[2] };
  if (right[0] === 0) return { status: "UNDEFINED_ZERO_DENOMINATOR", unit: left[2] };
  const numerator = BigInt(left[0]) * BigInt(right[1]); const denominator = BigInt(left[1]) * BigInt(right[0]); const divisor = gcd(numerator, denominator);
  const n = numerator / divisor; const d = denominator / divisor;
  if (n > BigInt(Number.MAX_SAFE_INTEGER) || d > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("derived ratio exceeds the safe-integer boundary");
  return { status: "ESTABLISHED", numerator: Number(n), denominator: Number(d), unit: left[2] };
}

export function calculate(data: RecordValue): RecordValue {
  if (!data || typeof data !== "object" || Array.isArray(data)) throw new TypeError("data must be an object");
  const query = data.query;
  if (!query || typeof query !== "object" || Array.isArray(query)) throw new TypeError("query must be an object");
  const validAtText = text(query.validAt, "query.validAt"); const knownAtText = text(query.knownAt, "query.knownAt");
  const validAt = instant(validAtText, "query.validAt"); const knownAt = instant(knownAtText, "query.knownAt");
  const rootId = text(query.rootEntityId, "query.rootEntityId"); const compareIds = query.compareShareClassIds;
  if (!Array.isArray(compareIds) || compareIds.length !== 2 || compareIds.some((item: unknown) => typeof item !== "string" || item === "")) throw new RangeError("query.compareShareClassIds must contain exactly two IDs");

  if (!Array.isArray(data.entities) || data.entities.length === 0) throw new RangeError("entities must be a non-empty list");
  const entityById = new Map<string, RecordValue>();
  data.entities.forEach((entity: unknown, index: number) => {
    const name = `entities[${index}]`; if (!entity || typeof entity !== "object" || Array.isArray(entity)) throw new TypeError(`${name} must be an object`);
    const item = entity as RecordValue; const entityId = text(item.entityId, `${name}.entityId`); const entityType = text(item.entityType, `${name}.entityType`);
    if (!ENTITY_TYPES.has(entityType)) throw new RangeError(`${name}.entityType is unsupported`); if (entityById.has(entityId)) throw new RangeError(`duplicate entityId ${entityId}`); entityById.set(entityId, item);
  });
  if (!entityById.has(rootId)) throw new RangeError("rootEntityId is unknown"); if (entityById.get(rootId)!.entityType !== "SHARE_CLASS") throw new RangeError("rootEntityId must identify a SHARE_CLASS");
  for (const id of compareIds) if (!entityById.has(id) || entityById.get(id)!.entityType !== "SHARE_CLASS") throw new RangeError("compareShareClassIds must identify SHARE_CLASS entities");

  if (!Array.isArray(data.relationships) || data.relationships.length === 0) throw new RangeError("relationships must be a non-empty list");
  const grouped = new Map<string, RecordValue[]>(); const immutable = new Map<string, string>(); const seen = new Set<string>();
  data.relationships.forEach((relation: unknown, index: number) => {
    const name = `relationships[${index}]`; if (!relation || typeof relation !== "object" || Array.isArray(relation)) throw new TypeError(`${name} must be an object`); const item = relation as RecordValue;
    const assertionId = text(item.assertionId, `${name}.assertionId`); const revisionNumber = safeInt(item.revisionNumber, `${name}.revisionNumber`); const revisionKey = `${assertionId}\0${revisionNumber}`;
    if (seen.has(revisionKey)) throw new RangeError(`duplicate revision ${assertionId}/${revisionNumber}`); seen.add(revisionKey);
    const relationshipType = text(item.relationshipType, `${name}.relationshipType`); if (!RELATIONSHIP_TYPES.has(relationshipType)) throw new RangeError(`${name}.relationshipType is unsupported`);
    const sourceId = text(item.sourceEntityId, `${name}.sourceEntityId`); const targetId = text(item.targetEntityId, `${name}.targetEntityId`); if (sourceId === targetId) throw new RangeError(`${name} cannot be self-referential`);
    if (!entityById.has(sourceId) || !entityById.has(targetId)) throw new RangeError(`${name} refers to an unknown entity`);
    const [sourceTypes, targetTypes] = ENDPOINTS[relationshipType]; if (!sourceTypes.has(entityById.get(sourceId)!.entityType) || !targetTypes.has(entityById.get(targetId)!.entityType)) throw new RangeError(`${name} has invalid endpoint types for ${relationshipType}`);
    const signature = `${relationshipType}\0${sourceId}\0${targetId}`; if (immutable.has(assertionId) && immutable.get(assertionId) !== signature) throw new RangeError(`${assertionId} changes type or endpoints across revisions`); immutable.set(assertionId, signature);
    const observed = instant(item.observedAt, `${name}.observedAt`); const available = instant(item.availableAt, `${name}.availableAt`); if (available < observed) throw new RangeError(`${name}.availableAt precedes observedAt`);
    const effectiveFrom = instant(item.effectiveFrom, `${name}.effectiveFrom`); if (item.effectiveTo !== null && item.effectiveTo !== undefined && instant(item.effectiveTo, `${name}.effectiveTo`) <= effectiveFrom) throw new RangeError(`${name}.effectiveTo must follow effectiveFrom`);
    if (!new Set(["ACTIVE", "CANCELLED"]).has(item.status)) throw new RangeError(`${name}.status must be ACTIVE or CANCELLED`); validateSource(item.source, name); validateTerms(item, name);
    const group = grouped.get(assertionId) ?? []; group.push(item); grouped.set(assertionId, group);
  });

  const selected: RecordValue[] = []; const selectedRevision: Record<string, number> = {}; const cancelled: string[] = []; let futureCount = 0;
  for (const assertionId of [...grouped.keys()].sort()) {
    const group = grouped.get(assertionId)!.slice().sort((a, b) => a.revisionNumber - b.revisionNumber);
    for (let index = 1; index < group.length; index++) {
      if (group[index].revisionNumber <= group[index - 1].revisionNumber) throw new RangeError(`${assertionId} revisions are not increasing`);
      if (instant(group[index].availableAt, "availableAt") <= instant(group[index - 1].availableAt, "availableAt")) throw new RangeError(`${assertionId} availability must increase with revision number`);
    }
    const available = group.filter(item => instant(item.availableAt, "availableAt") <= knownAt); futureCount += group.length - available.length; if (!available.length) continue;
    const latest = available[available.length - 1]; selectedRevision[assertionId] = latest.revisionNumber; if (latest.status === "CANCELLED") { cancelled.push(assertionId); continue; }
    const start = instant(latest.effectiveFrom, "effectiveFrom"); const end = latest.effectiveTo == null ? null : instant(latest.effectiveTo, "effectiveTo"); if (start <= validAt && (end === null || validAt < end)) selected.push(latest);
  }
  selected.sort((a, b) => [a.relationshipType, a.sourceEntityId, a.targetEntityId, a.assertionId].join("\0").localeCompare([b.relationshipType, b.sourceEntityId, b.targetEntityId, b.assertionId].join("\0")));

  const conflictGroups = new Map<string, RecordValue[]>(); for (const item of selected) { const key = [item.relationshipType, item.sourceEntityId, item.targetEntityId].join("\0"); const group = conflictGroups.get(key) ?? []; group.push(item); conflictGroups.set(key, group); }
  const conflicts: RecordValue[] = [];
  for (const key of [...conflictGroups.keys()].sort()) { const relations = conflictGroups.get(key)!; const signatures = new Set(relations.map(item => JSON.stringify(item.terms, Object.keys(item.terms).sort()))); if (relations.length > 1 && signatures.size > 1) { const [relationshipType, sourceEntityId, targetEntityId] = key.split("\0"); conflicts.push({ relationshipType, sourceEntityId, targetEntityId, assertionIds: relations.map(item => item.assertionId).sort() }); } }
  const unsupported = selected.filter(item => (item.unsupportedTerms ?? []).length).map(item => ({ assertionId: item.assertionId, terms: [...item.unsupportedTerms] })); const state = conflicts.length ? "CONFLICT" : unsupported.length ? "INCOMPLETE" : "RESOLVED";
  const edges = (relationshipType: string, sourceId?: string) => selected.filter(item => item.relationshipType === relationshipType && (sourceId === undefined || item.sourceEntityId === sourceId));

  const legalIds = new Set(edges("CLASS_OF", rootId).map(item => item.targetEntityId)); const issuerIds = new Set(edges("ISSUED_BY").filter(item => legalIds.has(item.sourceEntityId)).map(item => item.targetEntityId));
  const issuerLegalIds = new Set(edges("ISSUED_BY").filter(item => issuerIds.has(item.targetEntityId)).map(item => item.sourceEntityId)); const sameIssuerClasses = [...new Set(edges("CLASS_OF").filter(item => issuerLegalIds.has(item.targetEntityId)).map(item => item.sourceEntityId))].sort();
  const [leftId, rightId] = compareIds as [string, string];
  const rights = (relationshipType: string, classId: string): [number, number, string] | null => { const found = edges(relationshipType, classId); return found.length === 1 ? ratio(found[0].terms, found[0].assertionId, relationshipType === "VOTING_RIGHTS") : null; };
  const leftEconomic = edges("ECONOMIC_RIGHTS", leftId), rightEconomic = edges("ECONOMIC_RIGHTS", rightId); let equalEconomics: boolean | string = "UNKNOWN";
  if (leftEconomic.length === 1 && rightEconomic.length === 1 && !(leftEconomic[0].unsupportedTerms ?? []).length && !(rightEconomic[0].unsupportedTerms ?? []).length) equalEconomics = JSON.stringify(leftEconomic[0].terms) === JSON.stringify(rightEconomic[0].terms);
  const conversionEdges = selected.filter(item => ["CONVERTS_TO", "EXCHANGES_TO"].includes(item.relationshipType) && item.sourceEntityId === leftId && item.targetEntityId === rightId);
  const conversion = conversionEdges.length === 1 ? { status: "ESTABLISHED", direction: `${leftId}->${rightId}`, relationshipType: conversionEdges[0].relationshipType, ratio: reduced(conversionEdges[0].terms.numerator, conversionEdges[0].terms.denominator), unit: conversionEdges[0].terms.unit, conditions: [...conversionEdges[0].terms.conditions] } : { status: "NOT_ESTABLISHED" };
  const fungibleEdges = edges("FUNGIBLE_WITH").filter(item => new Set([item.sourceEntityId, item.targetEntityId]).size === 2 && [item.sourceEntityId, item.targetEntityId].includes(leftId) && [item.sourceEntityId, item.targetEntityId].includes(rightId));
  const fungibility = fungibleEdges.length === 1 ? { status: "ESTABLISHED", conditions: [...fungibleEdges[0].terms.conditions] } : { status: "NOT_ESTABLISHED" };
  const resolvedRelationships = selected.map(item => ({ assertionId: item.assertionId, revisionNumber: item.revisionNumber, relationshipType: item.relationshipType, sourceEntityId: item.sourceEntityId, targetEntityId: item.targetEntityId, effectiveFrom: item.effectiveFrom, effectiveTo: item.effectiveTo ?? null, observedAt: item.observedAt, availableAt: item.availableAt, source: structuredClone(item.source), terms: structuredClone(item.terms), unsupportedTerms: [...(item.unsupportedTerms ?? [])] }));

  return {
    query: { rootEntityId: rootId, validAt: validAtText, knownAt: knownAtText }, root: { entityId: rootId, entityType: entityById.get(rootId)!.entityType }, state,
    sameIssuerShareClassIds: sameIssuerClasses,
    comparison: { leftShareClassId: leftId, rightShareClassId: rightId, votingRightsRatioLeftToRight: divideRatios(rights("VOTING_RIGHTS", leftId), rights("VOTING_RIGHTS", rightId)), economicRightsRatioLeftToRight: divideRatios(rights("ECONOMIC_RIGHTS", leftId), rights("ECONOMIC_RIGHTS", rightId)), equalEconomics, conversion, fungibility, priceConvertibility: "NOT_ESTABLISHED" },
    resolvedRelationships,
    diagnostics: { selectedRevisionByAssertion: selectedRevision, excludedFutureRevisionCount: futureCount, cancelledAssertionIds: cancelled, conflicts, unsupportedTerms: unsupported },
  };
}