Historical Constituent Reconstruction: Rebuild the Roster Without Looking Ahead

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

/** Bitemporal historical constituent reconstruction for D02-F04-A01. */
const UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/;
const SUPPORTED = new Set(["add", "delete", "replace", "rebalance", "reconstitution", "corporate_action"]);

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 instant = (value: unknown, name: string): number => {
  const valueText = textValue(value, name);
  if (!UTC.test(valueText)) throw new RangeError(`${name} must be a strict UTC ISO 8601 instant ending in Z`);
  const parsed = Date.parse(valueText);
  if (!Number.isFinite(parsed)) throw new RangeError(`${name} is not a calendar-valid instant`);
  const [, year, month, day, hour, minute, second] = valueText.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/)!.map(Number);
  const d = new Date(parsed);
  if (d.getUTCFullYear() !== year || d.getUTCMonth() + 1 !== month || d.getUTCDate() !== day || d.getUTCHours() !== hour || d.getUTCMinutes() !== minute || d.getUTCSeconds() !== second) {
    throw new RangeError(`${name} is not a calendar-valid instant`);
  }
  return parsed;
};
const positiveInt = (value: unknown, name: string): number => {
  if (!Number.isSafeInteger(value) || (value as number) < 1) throw new TypeError(`${name} must be a positive safe integer`);
  return value as number;
};
const nonnegativeInt = (value: unknown, name: string): number => {
  if (!Number.isSafeInteger(value) || (value as number) < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
  return value as number;
};
const textList = (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 RangeError(`${name} must not contain duplicates`);
  return checked;
};

type Change = { action: "add" | "delete"; securityId: string };
type Snapshot = { snapshotId: string; revision: number; effectiveAt: string; effectiveInstant: number; availableAt: string; availableInstant: number; lastSequence: number; status: "active" | "cancelled"; securityIds: string[]; sourceId: string };
type EventVersion = { eventId: string; revision: number; sequence: number; eventType: string; effectiveOrder: number; effectiveAt: string; effectiveInstant: number; announcedAt: string; announcedInstant: number; availableAt: string; availableInstant: number; status: "active" | "cancelled"; changes: Change[]; sourceId: string };

const emptyResult = (status: string, indexId: string, effectiveAt: string, knownAt: string, diagnostics: string[], extra: Record<string, unknown> = {}) => ({
  status, indexId, effectiveAt, knownAt, securityIds: [], membershipIntervals: [], appliedEventVersions: [], cancelledEventIds: [], diagnostics, ...extra,
});

function validateSnapshots(raw: unknown, indexId: string): Snapshot[] {
  if (!Array.isArray(raw) || raw.length === 0) throw new TypeError("snapshots must be a non-empty list");
  const snapshots = raw.map((item: any, i): Snapshot => {
    if (!item || typeof item !== "object" || Array.isArray(item)) throw new TypeError(`snapshots[${i}] must be an object`);
    const p = `snapshots[${i}]`;
    if (textValue(item.indexId, `${p}.indexId`) !== indexId) throw new RangeError(`${p}.indexId does not match indexId`);
    const status = textValue(item.status, `${p}.status`);
    if (status !== "active" && status !== "cancelled") throw new RangeError(`${p}.status must be active or cancelled`);
    const effectiveAt = textValue(item.effectiveAt, `${p}.effectiveAt`);
    const availableAt = textValue(item.availableAt, `${p}.availableAt`);
    return { snapshotId: textValue(item.snapshotId, `${p}.snapshotId`), revision: positiveInt(item.revision, `${p}.revision`), effectiveAt, effectiveInstant: instant(effectiveAt, `${p}.effectiveAt`), availableAt, availableInstant: instant(availableAt, `${p}.availableAt`), lastSequence: nonnegativeInt(item.lastSequence, `${p}.lastSequence`), status, securityIds: textList(item.securityIds, `${p}.securityIds`, true), sourceId: textValue(item.sourceId, `${p}.sourceId`) };
  });
  for (const snapshotId of [...new Set(snapshots.map((s) => s.snapshotId))]) {
    const versions = snapshots.filter((s) => s.snapshotId === snapshotId).sort((a, b) => a.revision - b.revision);
    if (versions.some((v, i) => v.revision !== i + 1)) throw new RangeError(`snapshot ${snapshotId} revisions must be contiguous from 1`);
    if (new Set(versions.map((v) => `${v.effectiveAt}|${v.lastSequence}`)).size !== 1) throw new RangeError(`snapshot ${snapshotId} changes immutable anchor fields`);
    if (versions.some((v, i) => i > 0 && v.availableInstant <= versions[i - 1].availableInstant)) throw new RangeError(`snapshot ${snapshotId} availability must increase with revision`);
  }
  return snapshots;
}

function validateEvents(raw: unknown, indexId: string): EventVersion[] {
  if (!Array.isArray(raw)) throw new TypeError("events must be a list");
  const events = raw.map((item: any, i): EventVersion => {
    if (!item || typeof item !== "object" || Array.isArray(item)) throw new TypeError(`events[${i}] must be an object`);
    const p = `events[${i}]`;
    if (textValue(item.indexId, `${p}.indexId`) !== indexId) throw new RangeError(`${p}.indexId does not match indexId`);
    const status = textValue(item.status, `${p}.status`);
    if (status !== "active" && status !== "cancelled") throw new RangeError(`${p}.status must be active or cancelled`);
    const announcedAt = textValue(item.announcedAt, `${p}.announcedAt`); const announcedInstant = instant(announcedAt, `${p}.announcedAt`);
    const availableAt = textValue(item.availableAt, `${p}.availableAt`); const availableInstant = instant(availableAt, `${p}.availableAt`);
    if (availableInstant < announcedInstant) throw new RangeError(`${p}.availableAt cannot precede announcedAt`);
    if (!Array.isArray(item.changes)) throw new TypeError(`${p}.changes must be a list`);
    const changes = item.changes.map((c: any, j): Change => {
      if (!c || typeof c !== "object" || Array.isArray(c)) throw new TypeError(`${p}.changes[${j}] must be an object`);
      const action = textValue(c.action, `${p}.changes[${j}].action`);
      if (action !== "add" && action !== "delete") throw new RangeError(`${p}.changes[${j}].action must be add or delete`);
      return { action, securityId: textValue(c.securityId, `${p}.changes[${j}].securityId`) };
    });
    if (new Set(changes.map((c) => c.securityId)).size !== changes.length) throw new RangeError(`${p}.changes may target each stable securityId only once`);
    if (status === "cancelled" && changes.length) throw new RangeError(`${p}.changes must be empty for a cancellation`);
    const effectiveAt = textValue(item.effectiveAt, `${p}.effectiveAt`);
    const eventType = textValue(item.eventType, `${p}.eventType`);
    if (status === "active" && SUPPORTED.has(eventType)) {
      const adds = changes.filter((c) => c.action === "add").length, deletes = changes.filter((c) => c.action === "delete").length;
      const validShape: Record<string, boolean> = { add: adds === 1 && deletes === 0, delete: adds === 0 && deletes === 1, replace: adds === 1 && deletes === 1, rebalance: adds === 0 && deletes === 0, reconstitution: adds + deletes > 0, corporate_action: adds + deletes > 0 };
      if (!validShape[eventType]) throw new RangeError(`${p}.changes does not match eventType ${eventType}`);
    }
    return { eventId: textValue(item.eventId, `${p}.eventId`), revision: positiveInt(item.revision, `${p}.revision`), sequence: positiveInt(item.sequence, `${p}.sequence`), eventType, effectiveOrder: nonnegativeInt(item.effectiveOrder, `${p}.effectiveOrder`), effectiveAt, effectiveInstant: instant(effectiveAt, `${p}.effectiveAt`), announcedAt, announcedInstant, availableAt, availableInstant, status, changes, sourceId: textValue(item.sourceId, `${p}.sourceId`) };
  });
  for (const eventId of [...new Set(events.map((e) => e.eventId))]) {
    const versions = events.filter((e) => e.eventId === eventId).sort((a, b) => a.revision - b.revision);
    if (versions.some((v, i) => v.revision !== i + 1)) throw new RangeError(`event ${eventId} revisions must be contiguous from 1`);
    if (new Set(versions.map((v) => `${v.sequence}|${v.eventType}|${v.effectiveAt}|${v.effectiveOrder}`)).size !== 1) throw new RangeError(`event ${eventId} changes immutable identity fields`);
    if (versions.some((v, i) => i > 0 && v.availableInstant <= versions[i - 1].availableInstant)) throw new RangeError(`event ${eventId} availability must increase with revision`);
  }
  return events;
}

export function calculate(data: any) {
  if (!data || typeof data !== "object" || Array.isArray(data)) throw new TypeError("data must be an object");
  const indexId = textValue(data.indexId, "indexId"); const effectiveAt = textValue(data.effectiveAt, "effectiveAt"); const knownAt = textValue(data.knownAt, "knownAt");
  const effective = instant(effectiveAt, "effectiveAt"); const known = instant(knownAt, "knownAt");
  const snapshots = validateSnapshots(data.snapshots, indexId); const events = validateEvents(data.events, indexId);
  const eligibleSnapshots: Snapshot[] = [];
  for (const snapshotId of [...new Set(snapshots.map((s) => s.snapshotId))].sort()) {
    const eligible = snapshots.filter((s) => s.snapshotId === snapshotId && s.availableInstant <= known).sort((a, b) => b.revision - a.revision);
    if (eligible.length && eligible[0].status === "active" && eligible[0].effectiveInstant <= effective) eligibleSnapshots.push(eligible[0]);
  }
  if (!eligibleSnapshots.length) return emptyResult("incomplete", indexId, effectiveAt, knownAt, ["no active base snapshot was available by knownAt and effective by effectiveAt"]);
  const chronologicalAnchors = [...eligibleSnapshots].sort((a, b) => a.effectiveInstant - b.effectiveInstant || a.snapshotId.localeCompare(b.snapshotId)); let highestSequence = -1;
  for (const candidate of chronologicalAnchors) { if (candidate.lastSequence < highestSequence) return emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`base snapshot ${candidate.snapshotId} regresses lastSequence relative to an earlier eligible snapshot`]); highestSequence = Math.max(highestSequence, candidate.lastSequence); }
  const anchorTime = Math.max(...eligibleSnapshots.map((s) => s.effectiveInstant)); const anchors = eligibleSnapshots.filter((s) => s.effectiveInstant === anchorTime);
  if (anchors.length !== 1) return emptyResult("ambiguous", indexId, effectiveAt, knownAt, ["multiple active base snapshots overlap at the latest effective instant"]);
  const anchor = anchors[0]; const selected: EventVersion[] = []; const cancelled: string[] = [];
  for (const eventId of [...new Set(events.map((e) => e.eventId))].sort()) {
    const all = events.filter((e) => e.eventId === eventId);
    const eligible = all.filter((e) => e.availableInstant <= known).sort((a, b) => b.revision - a.revision);
    if (eligible.length && eligible[0].sequence > anchor.lastSequence && eligible[0].effectiveInstant <= effective) { selected.push(eligible[0]); if (eligible[0].status === "cancelled") cancelled.push(eventId); }
  }
  const anchorConflict = selected.filter((e) => e.effectiveInstant <= anchor.effectiveInstant).map((e) => e.eventId).sort()[0];
  if (anchorConflict) return { ...emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`event ${anchorConflict} is effective at or before the base snapshot but claims a later sequence`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision };
  const active = selected.filter((e) => e.status === "active"); const unsupported = active.filter((e) => !SUPPORTED.has(e.eventType)).map((e) => e.eventId).sort();
  if (unsupported.length) return { ...emptyResult("unsupported", indexId, effectiveAt, knownAt, ["unsupported event types are present"], { unsupportedEventIds: unsupported }), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision };
  const bySequence = new Map<number, EventVersion[]>(); selected.forEach((e) => bySequence.set(e.sequence, [...(bySequence.get(e.sequence) ?? []), e]));
  const duplicate = [...bySequence].filter(([, values]) => values.length > 1).map(([sequence]) => sequence).sort((a, b) => a - b)[0];
  if (duplicate !== undefined) return { ...emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`multiple event identities claim sequence ${duplicate}`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision };
  const relevantSequences = [...bySequence.keys()].sort((a, b) => a - b);
  if (relevantSequences.length) { const missing: number[] = []; for (let n = anchor.lastSequence + 1; n <= relevantSequences.at(-1)!; n++) if (!bySequence.has(n)) missing.push(n); if (missing.length) return { ...emptyResult("incomplete", indexId, effectiveAt, knownAt, [`event sequence gap at ${missing.join(", ")}; no gap was filled`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision }; }
  const slots = new Map<string, Set<string>>(); active.forEach((e) => e.changes.forEach((c) => { const key = `${e.effectiveAt}|${e.effectiveOrder}|${c.securityId}`; slots.set(key, new Set([...(slots.get(key) ?? []), e.eventId])); }));
  const conflict = [...slots].filter(([, ids]) => ids.size > 1).map(([key]) => key).sort()[0];
  if (conflict) { const [at, order, securityId] = conflict.split("|"); return { ...emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`conflicting same-instant evidence for ${securityId} at ${at}, order ${order}`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision }; }
  const open = new Map(anchor.securityIds.map((id) => [id, anchor.effectiveAt])); const closed: any[] = []; const applied: string[] = [];
  const ordered = active.sort((a, b) => a.effectiveInstant - b.effectiveInstant || a.effectiveOrder - b.effectiveOrder || a.sequence - b.sequence || a.eventId.localeCompare(b.eventId));
  for (const event of ordered) {
    for (const change of event.changes.filter((c) => c.action === "delete").sort((a, b) => a.securityId.localeCompare(b.securityId))) { if (!open.has(change.securityId)) return { ...emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`event ${event.eventId} deletes absent security ${change.securityId}`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision }; closed.push({ securityId: change.securityId, validFrom: open.get(change.securityId), validTo: event.effectiveAt }); open.delete(change.securityId); }
    for (const change of event.changes.filter((c) => c.action === "add").sort((a, b) => a.securityId.localeCompare(b.securityId))) { if (open.has(change.securityId)) return { ...emptyResult("ambiguous", indexId, effectiveAt, knownAt, [`event ${event.eventId} adds existing security ${change.securityId}`]), baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision }; open.set(change.securityId, event.effectiveAt); }
    applied.push(`${event.eventId}@${event.revision}`);
  }
  const intervals = [...closed, ...[...open].map(([securityId, validFrom]) => ({ securityId, validFrom, validTo: null }))].sort((a, b) => a.securityId.localeCompare(b.securityId) || a.validFrom.localeCompare(b.validFrom) || (a.validTo ?? "").localeCompare(b.validTo ?? ""));
  return { status: "resolved", indexId, effectiveAt, knownAt, baseSnapshotId: anchor.snapshotId, baseRevision: anchor.revision, securityIds: [...open.keys()].sort(), membershipIntervals: intervals, appliedEventVersions: applied, cancelledEventIds: cancelled.sort(), diagnostics: [] };
}