IPO Availability Timestamping: Separate Listing Events from Research Knowledge

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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245

/** Bitemporal IPO evidence selection for D02-F04-A03. */

const EVENT_TYPES = [
  "issuer_filing", "registration_effective", "listing_notice", "offer_pricing", "allocation",
  "first_eligible_session", "first_observed_quote", "first_observed_trade", "vendor_release", "local_ingestion",
];
const EVENT_ORDER = new Map(EVENT_TYPES.map((name, index) => [name, index]));
const CONTEXTS = new Set(["traditional_ipo", "direct_listing_resale", "direct_listing_capital_raise", "spac_ipo", "de_spac", "uplisting"]);
const MARKET_PHASES = new Set(["all", "regular", "when_issued"]);
const STATES = new Set(["active", "cancelled"]);
const OWNER_BY_EVENT = {
  issuer_filing: new Set(["regulator"]), registration_effective: new Set(["regulator"]),
  listing_notice: new Set(["exchange"]), offer_pricing: new Set(["issuer", "underwriter"]),
  allocation: new Set(["underwriter"]), first_eligible_session: new Set(["exchange"]),
  first_observed_quote: new Set(["venue", "vendor"]), first_observed_trade: new Set(["venue", "vendor"]),
  vendor_release: new Set(["vendor"]), local_ingestion: new Set(["research_system"]),
};
const PHASE_SPECIFIC = new Set(["first_eligible_session", "first_observed_quote", "first_observed_trade"]);

const textValue = (value, name) => {
  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
  return value;
};
const instant = (value, name) => {
  const text = textValue(value, name);
  if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(text)) throw new RangeError(`${name} must include a UTC offset`);
  const milliseconds = Date.parse(text);
  if (!Number.isFinite(milliseconds)) throw new RangeError(`${name} must be a valid ISO 8601 instant`);
  return milliseconds;
};
const positiveInteger = (value, name) => {
  if (!Number.isInteger(value) || value < 1) throw new TypeError(`${name} must be a positive integer`);
  return value;
};
const enumValue = (value, name, choices) => {
  const text = textValue(value, name);
  if (!choices.has(text)) throw new RangeError(`${name} is unsupported`);
  return text;
};
const isoZ = milliseconds => new Date(milliseconds).toISOString().replace(".000Z", "Z");

function knownItems(raw, knownAt, name, allowEmpty = false) {
  if (!Array.isArray(raw) || (!raw.length && !allowEmpty)) throw new TypeError(`${name} must be ${allowEmpty ? "a list" : "a non-empty list"}`);
  return raw.flatMap((item, index) => {
    if (!item || typeof item !== "object" || Array.isArray(item)) throw new TypeError(`${name}[${index}] must be an object`);
    return instant(item.availableAt, `${name}[${index}].availableAt`) <= knownAt ? [[index, item]] : [];
  });
}

function revisionCurrent(records, label, immutable) {
  const ordered = records.toSorted((left, right) => left.revision - right.revision);
  if (ordered.some((record, index) => record.revision !== index + 1)) throw new RangeError(`${label} revisions must be contiguous from 1`);
  const first = ordered[0];
  let priorAvailable = null;
  let cancelled = false;
  for (const record of ordered) {
    if (immutable.some(field => JSON.stringify(record[field]) !== JSON.stringify(first[field]))) throw new RangeError(`${label} changed immutable identity or provenance`);
    if (priorAvailable !== null && record.availableInstant <= priorAvailable) throw new RangeError(`${label} revision availability must increase`);
    if (record.state === "cancelled") {
      if (record.revision === 1) throw new RangeError(`${label} cannot begin cancelled`);
      cancelled = true;
    } else if (cancelled) throw new RangeError(`${label} cannot reactivate after cancellation`);
    priorAvailable = record.availableInstant;
  }
  return ordered.at(-1);
}

function validatePolicy(item, index) {
  const prefix = `policies[${index}]`;
  if (!Array.isArray(item.requiredEventTypes) || !item.requiredEventTypes.length) throw new TypeError(`${prefix}.requiredEventTypes must be a non-empty list`);
  const requiredEventTypes = item.requiredEventTypes.map(value => enumValue(value, `${prefix}.requiredEventTypes item`, new Set(EVENT_TYPES)));
  if (new Set(requiredEventTypes).size !== requiredEventTypes.length) throw new RangeError(`${prefix}.requiredEventTypes must be unique`);
  return {
    ...item, policyId: textValue(item.policyId, `${prefix}.policyId`), revision: positiveInteger(item.revision, `${prefix}.revision`),
    state: enumValue(item.state, `${prefix}.state`, STATES), effectiveInstant: instant(item.effectiveAt, `${prefix}.effectiveAt`),
    availableInstant: instant(item.availableAt, `${prefix}.availableAt`), sourceId: textValue(item.sourceId, `${prefix}.sourceId`),
    context: enumValue(item.context, `${prefix}.context`, CONTEXTS),
    marketPhase: enumValue(item.marketPhase, `${prefix}.marketPhase`, new Set(["regular", "when_issued"])), requiredEventTypes,
  };
}

function selectPolicy(raw, policyId, effectiveAt, knownAt) {
  const relevant = knownItems(raw, knownAt, "policies").map(([index, item]) => validatePolicy(item, index))
    .filter(item => item.policyId === policyId && item.effectiveInstant <= effectiveAt);
  if (!relevant.length) return null;
  const current = revisionCurrent(relevant, `policy ${policyId}`, ["policyId", "sourceId", "context", "marketPhase"]);
  return current.state === "cancelled" ? null : current;
}

function validateEvent(item, index) {
  const prefix = `records[${index}]`;
  const eventType = enumValue(item.eventType, `${prefix}.eventType`, new Set(EVENT_TYPES));
  const clockOwner = textValue(item.clockOwner, `${prefix}.clockOwner`);
  if (!OWNER_BY_EVENT[eventType].has(clockOwner)) throw new RangeError(`${prefix}.clockOwner does not own the ${eventType} clock`);
  const marketPhase = enumValue(item.marketPhase, `${prefix}.marketPhase`, MARKET_PHASES);
  if (PHASE_SPECIFIC.has(eventType) && marketPhase === "all") throw new RangeError(`${prefix}.marketPhase must distinguish regular from when_issued`);
  if (!PHASE_SPECIFIC.has(eventType) && marketPhase !== "all") throw new RangeError(`${prefix}.marketPhase must be all for a non-session event`);
  const checked = {
    ...item, eventId: textValue(item.eventId, `${prefix}.eventId`), revision: positiveInteger(item.revision, `${prefix}.revision`),
    state: enumValue(item.state, `${prefix}.state`, STATES), eventType,
    issuerId: textValue(item.issuerId, `${prefix}.issuerId`), instrumentId: textValue(item.instrumentId, `${prefix}.instrumentId`),
    listingId: textValue(item.listingId, `${prefix}.listingId`), marketPhase,
    effectiveInstant: instant(item.effectiveAt, `${prefix}.effectiveAt`), availableInstant: instant(item.availableAt, `${prefix}.availableAt`),
    clockOwner, sourceId: textValue(item.sourceId, `${prefix}.sourceId`),
  };
  if (eventType === "first_eligible_session") {
    checked.calendarId = textValue(item.calendarId, `${prefix}.calendarId`);
    checked.sessionId = textValue(item.sessionId, `${prefix}.sessionId`);
  }
  return checked;
}

function currentEvents(records) {
  const byEvent = new Map();
  for (const record of records) byEvent.set(record.eventId, [...(byEvent.get(record.eventId) || []), record]);
  const immutable = ["eventType", "issuerId", "instrumentId", "listingId", "marketPhase", "clockOwner", "sourceId"];
  return [...byEvent].map(([eventId, revisions]) => revisionCurrent(revisions, `event ${eventId}`, immutable));
}

function resolveType(records) {
  const active = records.filter(record => record.state === "active");
  if (!active.length) return [null, false];
  if (new Set(active.map(record => record.effectiveInstant)).size !== 1) return [null, true];
  const primary = active.toSorted((left, right) => left.availableInstant - right.availableInstant || left.sourceId.localeCompare(right.sourceId) || left.eventId.localeCompare(right.eventId))[0];
  return [{ ...primary, corroboratingSources: [...new Set(active.map(record => record.sourceId))].sort() }, false];
}

function validateLink(item, index) {
  const prefix = `identityLinks[${index}]`;
  const checked = {
    ...item, linkId: textValue(item.linkId, `${prefix}.linkId`), revision: positiveInteger(item.revision, `${prefix}.revision`),
    state: enumValue(item.state, `${prefix}.state`, STATES),
    relationshipType: enumValue(item.relationshipType, `${prefix}.relationshipType`, new Set(["de_spac_successor"])),
    sourceId: textValue(item.sourceId, `${prefix}.sourceId`),
    sourceType: enumValue(item.sourceType, `${prefix}.sourceType`, new Set(["issuer_filing", "exchange_notice", "security_master"])),
    effectiveInstant: instant(item.effectiveAt, `${prefix}.effectiveAt`), availableInstant: instant(item.availableAt, `${prefix}.availableAt`),
  };
  for (const side of ["predecessor", "successor"]) {
    if (!item[side] || typeof item[side] !== "object" || Array.isArray(item[side])) throw new TypeError(`${prefix}.${side} must be an object`);
    checked[side] = {
      issuerId: textValue(item[side].issuerId, `${prefix}.${side}.issuerId`),
      instrumentId: textValue(item[side].instrumentId, `${prefix}.${side}.instrumentId`),
      listingId: textValue(item[side].listingId, `${prefix}.${side}.listingId`),
    };
  }
  return checked;
}

function selectIdentityLink(raw, identity, effectiveAt, knownAt) {
  if (raw == null) return [null, "missing"];
  const checked = knownItems(raw, knownAt, "identityLinks", true).map(([index, item]) => validateLink(item, index))
    .filter(item => JSON.stringify(item.successor) === JSON.stringify(identity) && item.effectiveInstant <= effectiveAt);
  const byLink = new Map();
  for (const item of checked) byLink.set(item.linkId, [...(byLink.get(item.linkId) || []), item]);
  const current = [...byLink].map(([linkId, revisions]) => revisionCurrent(revisions, `identity link ${linkId}`,
    ["linkId", "relationshipType", "sourceId", "sourceType", "predecessor", "successor"]));
  const active = current.filter(item => item.state === "active");
  if (active.length > 1) return [null, "ambiguous"];
  if (active.length === 1) return [active[0], "resolved"];
  return [null, current.some(item => item.state === "cancelled") ? "cancelled" : "missing"];
}

export function calculate(data) {
  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 identity = {
    issuerId: textValue(query.issuerId, "query.issuerId"), instrumentId: textValue(query.instrumentId, "query.instrumentId"),
    listingId: textValue(query.listingId, "query.listingId"),
  };
  const effectiveAt = textValue(query.effectiveAt, "query.effectiveAt");
  const knownAt = textValue(query.knownAt, "query.knownAt");
  const effectiveInstant = instant(effectiveAt, "query.effectiveAt");
  const knownInstant = instant(knownAt, "query.knownAt");
  const policyId = textValue(query.policyId, "query.policyId");
  const policy = selectPolicy(data.policies, policyId, effectiveInstant, knownInstant);
  const base = { effectiveAt, knownAt, identity: structuredClone(identity), policyId };
  const doesNotEstablish = ["investability", "tradability", "liquidity", "offering eligibility", "returns"];
  if (!policy) return {
    ...base, status: "incomplete", policySatisfied: false, policy: null, effectiveGateAt: null, knowledgeGateAt: null,
    missingPolicy: true, missingEventTypes: [], pendingEffectiveEventTypes: [], ambiguousEventTypes: [],
    supplementalAmbiguousEventTypes: [], cancelledEventTypes: [], unsupportedReasons: [],
    identityContinuityStatus: "not_evaluated", identityContinuityEvidence: null,
    evidence: [], doesNotEstablish,
  };

  const required = policy.requiredEventTypes;
  const knownEvents = knownItems(data.records, knownInstant, "records").map(([index, item]) => validateEvent(item, index));
  const knownCurrent = currentEvents(knownEvents);
  const relevant = knownCurrent.filter(record => Object.entries(identity).every(([key, value]) => record[key] === value)
    && (record.marketPhase === "all" || record.marketPhase === policy.marketPhase));
  const current = relevant;
  const cancelledEventTypes = [...new Set(current.filter(record => record.state === "cancelled").map(record => record.eventType))]
    .sort((left, right) => EVENT_ORDER.get(left) - EVENT_ORDER.get(right));
  const resolved = new Map();
  const ambiguousAll = [];
  for (const eventType of EVENT_TYPES) {
    const [selected, ambiguous] = resolveType(current.filter(record => record.eventType === eventType));
    if (selected) resolved.set(eventType, selected);
    if (ambiguous) ambiguousAll.push(eventType);
  }
  const missingEventTypes = required.filter(eventType => !resolved.has(eventType) && !ambiguousAll.includes(eventType));
  const ambiguousEventTypes = required.filter(eventType => ambiguousAll.includes(eventType));
  const pendingEffectiveEventTypes = required.filter(eventType => resolved.has(eventType) && resolved.get(eventType).effectiveInstant > effectiveInstant);
  const supplementalAmbiguousEventTypes = ambiguousAll.filter(eventType => !required.includes(eventType));
  const unsupportedReasons = [];
  if (policy.context === "direct_listing_resale" && ["offer_pricing", "allocation"].some(item => required.includes(item))) {
    unsupportedReasons.push("resale direct-listing policy cannot require underwritten offer pricing or allocation");
  }
  let identityLink = null;
  let identityContinuityStatus = "not_required";
  if (policy.context === "de_spac") {
    [identityLink, identityContinuityStatus] = selectIdentityLink(data.identityLinks, identity, effectiveInstant, knownInstant);
  }
  const status = unsupportedReasons.length ? "unsupported" :
    (ambiguousEventTypes.length || identityContinuityStatus === "ambiguous") ? "ambiguous" :
    (missingEventTypes.length || pendingEffectiveEventTypes.length || ["missing", "cancelled"].includes(identityContinuityStatus)) ? "incomplete" : "resolved";
  const evidence = EVENT_TYPES.flatMap(eventType => {
    const record = resolved.get(eventType);
    return record ? [{
      eventType, eventId: record.eventId, revision: record.revision, effectiveAt: record.effectiveAt, availableAt: record.availableAt,
      clockOwner: record.clockOwner, sourceId: record.sourceId, corroboratingSources: [...record.corroboratingSources],
      marketPhase: record.marketPhase, calendarId: record.calendarId ?? null, sessionId: record.sessionId ?? null,
    }] : [];
  });
  const effectiveGateAt = status === "resolved" ? isoZ(Math.max(policy.effectiveInstant, ...required.map(item => resolved.get(item).effectiveInstant))) : null;
  const knowledgeGateAt = status === "resolved" ? isoZ(Math.max(policy.availableInstant, ...required.map(item => resolved.get(item).availableInstant))) : null;
  const policyOutput = {
    policyId: policy.policyId, revision: policy.revision, sourceId: policy.sourceId, effectiveAt: policy.effectiveAt,
    availableAt: policy.availableAt, context: policy.context, marketPhase: policy.marketPhase,
    requiredEventTypes: [...required],
  };
  const identityContinuityEvidence = identityLink ? {
    linkId: identityLink.linkId, revision: identityLink.revision, relationshipType: identityLink.relationshipType,
    sourceId: identityLink.sourceId, sourceType: identityLink.sourceType, effectiveAt: identityLink.effectiveAt,
    availableAt: identityLink.availableAt, predecessor: structuredClone(identityLink.predecessor), successor: structuredClone(identityLink.successor),
  } : null;
  return {
    ...base, status, policySatisfied: status === "resolved", policy: policyOutput, effectiveGateAt, knowledgeGateAt,
    missingPolicy: false, missingEventTypes, pendingEffectiveEventTypes, ambiguousEventTypes,
    supplementalAmbiguousEventTypes, cancelledEventTypes, unsupportedReasons, identityContinuityStatus,
    identityContinuityEvidence, evidence, doesNotEstablish,
  };
}