Exchange-Calendar Alignment

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

/** Align UTC events to a pinned, explicit exchange-calendar bundle. */

export type EventKind =
  | "continuous"
  | "opening_auction"
  | "closing_auction"
  | "pre_market"
  | "post_market";

export type CalendarBundle = {
  calendar: Record<string, any>;
  sessions: Record<string, any>[];
  closed_dates: Record<string, any>[];
};

const VALID_EVENT_KINDS = new Set<EventKind>([
  "continuous",
  "opening_auction",
  "closing_auction",
  "pre_market",
  "post_market",
]);

function utcMs(value: unknown): number {
  if (typeof value !== "string" || !value.endsWith("Z")) {
    throw new Error("UTC instants must be strings ending in Z");
  }
  const parsed = Date.parse(value);
  if (!Number.isFinite(parsed)) throw new Error(`invalid UTC instant: ${value}`);
  return parsed;
}

function isoZ(value: number): string {
  return new Date(value).toISOString();
}

type LocalParts = { year: number; month: number; day: number; hour: number; minute: number; second: number };

function parseLocalWall(value: unknown): LocalParts & { millisecond: number } {
  if (typeof value !== "string") throw new Error("local wall time must be a string");
  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/.exec(value);
  if (!match) throw new Error(`invalid local wall time: ${value}`);
  const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
  const millisecond = Number((match[7] ?? "0").padEnd(3, "0"));
  const probe = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millisecond));
  if (
    probe.getUTCFullYear() !== year || probe.getUTCMonth() + 1 !== month || probe.getUTCDate() !== day ||
    probe.getUTCHours() !== hour || probe.getUTCMinutes() !== minute || probe.getUTCSeconds() !== second
  ) throw new Error(`invalid local wall time: ${value}`);
  return { year, month, day, hour, minute, second, millisecond };
}

function localPartsAt(instantMs: number, timeZone: string): LocalParts {
  let parts: Intl.DateTimeFormatPart[];
  try {
    parts = new Intl.DateTimeFormat("en-US", {
      timeZone,
      year: "numeric",
      month: "2-digit",
      day: "2-digit",
      hour: "2-digit",
      minute: "2-digit",
      second: "2-digit",
      hourCycle: "h23",
    }).formatToParts(new Date(instantMs));
  } catch (error) {
    throw new Error(`unknown IANA time zone: ${timeZone}`);
  }
  const value = (name: Intl.DateTimeFormatPartTypes) => Number(parts.find((part) => part.type === name)?.value);
  return { year: value("year"), month: value("month"), day: value("day"), hour: value("hour"), minute: value("minute"), second: value("second") };
}

function sameLocal(left: LocalParts, right: LocalParts): boolean {
  return left.year === right.year && left.month === right.month && left.day === right.day &&
    left.hour === right.hour && left.minute === right.minute && left.second === right.second;
}

const wallCandidateCache = new Map<string, number[]>();

export function localWallToUtc(localWall: string, timeZone: string, fold?: 0 | 1): string {
  const wall = parseLocalWall(localWall);
  const cacheKey = `${timeZone}|${localWall}`;
  let candidates = wallCandidateCache.get(cacheKey);
  if (!candidates) {
    const naive = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second, wall.millisecond);
    candidates = [];
    for (let offsetMinutes = -14 * 60; offsetMinutes <= 14 * 60; offsetMinutes += 1) {
      const candidate = naive - offsetMinutes * 60_000;
      if (sameLocal(localPartsAt(candidate, timeZone), wall) && !candidates.includes(candidate)) candidates.push(candidate);
    }
    candidates.sort((a, b) => a - b);
    wallCandidateCache.set(cacheKey, candidates);
  }
  if (!candidates.length) throw new Error("nonexistent local wall time");
  if (candidates.length > 1 && fold === undefined) throw new Error("ambiguous local wall time requires fold=0 or fold=1");
  if (fold !== undefined && fold !== 0 && fold !== 1) throw new Error("fold must be 0 or 1");
  return isoZ(candidates[candidates.length > 1 ? fold! : 0]);
}

function localDate(instantMs: number, timeZone: string): string {
  const p = localPartsAt(instantMs, timeZone);
  return `${p.year.toString().padStart(4, "0")}-${p.month.toString().padStart(2, "0")}-${p.day.toString().padStart(2, "0")}`;
}

export function validateCalendar(bundle: CalendarBundle): void {
  if (!bundle || typeof bundle !== "object" || !bundle.calendar || !Array.isArray(bundle.sessions) || !Array.isArray(bundle.closed_dates)) {
    throw new Error("bundle requires calendar, sessions, and closed_dates");
  }
  const c = bundle.calendar;
  const required = ["calendar_id", "calendar_version", "retrieved_at", "venue", "market", "time_zone", "tzdb_version", "supported_dates"];
  if (required.some((field) => !c[field])) throw new Error("calendar provenance fields must be populated");
  if (c.boundary !== "[open, close)") throw new Error("only open-inclusive, close-exclusive calendars are accepted");
  if (c.outside_coverage !== "fail_closed") throw new Error("outside_coverage must be fail_closed");
  if (c.local_time_policy !== "reject_nonexistent_require_fold_for_ambiguous") throw new Error("local-time resolution policy is not supported");
  if (!Array.isArray(c.supported_dates) || c.supported_dates.length !== new Set(c.supported_dates).size) throw new Error("supported_dates must be a unique list");

  const sessionDates = new Set<string>();
  const intervals: [number, number][] = [];
  for (const session of bundle.sessions) {
    const fields = ["session_id", "session_date", "local_open", "local_close", "open", "close", "session_type", "source_ids"];
    if (fields.some((field) => session[field] === undefined)) throw new Error("session is missing required fields");
    if (sessionDates.has(session.session_date)) throw new Error("only one core session is allowed per supported date");
    if (!Array.isArray(session.source_ids) || !session.source_ids.length) throw new Error("every session needs source provenance");
    const open = utcMs(session.open), close = utcMs(session.close);
    if (open >= close) throw new Error("session open must precede close");
    if (localWallToUtc(session.local_open, c.time_zone) !== isoZ(open)) throw new Error("local_open does not resolve to open");
    if (localWallToUtc(session.local_close, c.time_zone) !== isoZ(close)) throw new Error("local_close does not resolve to close");
    if (localDate(open, c.time_zone) !== session.session_date) throw new Error("session_date disagrees with local open date");
    sessionDates.add(session.session_date);
    intervals.push([open, close]);
  }
  intervals.sort((a, b) => a[0] - b[0]);
  for (let index = 1; index < intervals.length; index += 1) {
    if (intervals[index - 1][1] > intervals[index][0]) throw new Error("sessions overlap");
  }

  const closureDates = new Set<string>();
  for (const closure of bundle.closed_dates) {
    if (!["session_date", "closure_type", "reason", "source_ids"].every((field) => closure[field])) throw new Error("closure records require date, type, reason, and sources");
    if (closureDates.has(closure.session_date) || sessionDates.has(closure.session_date)) throw new Error("a date cannot be duplicated or both open and closed");
    closureDates.add(closure.session_date);
  }
  const explicit = new Set([...sessionDates, ...closureDates]);
  if (explicit.size !== c.supported_dates.length || c.supported_dates.some((date: string) => !explicit.has(date))) {
    throw new Error("supported_dates must exactly match explicit sessions and closures");
  }
}

export function alignEvents(events: Record<string, any>[], bundle: CalendarBundle): Record<string, any>[] {
  validateCalendar(bundle);
  const c = bundle.calendar;
  const sessions = new Map(bundle.sessions.map((row) => [row.session_date, row]));
  const closures = new Map(bundle.closed_dates.map((row) => [row.session_date, row]));
  const supported = new Set<string>(c.supported_dates);
  return events.map((event) => {
    if (!event || typeof event !== "object" || !event.event_id) throw new Error("every event requires event_id");
    if (!VALID_EVENT_KINDS.has(event.event_kind)) throw new Error(`unsupported event_kind: ${event.event_kind}`);
    const instant = utcMs(event.timestamp);
    const date = localDate(instant, c.time_zone);
    const common = {
      ...event,
      local_date: date,
      calendar_id: c.calendar_id,
      calendar_version: c.calendar_version,
      venue: c.venue,
      market: c.market,
      time_zone: c.time_zone,
      session_id: null,
      session_type: null,
      eligible: false,
      source_ids: [] as string[],
    };
    if (!supported.has(date)) return { ...common, status: "calendar_unsupported", reason: "local date is absent from the pinned calendar" };
    if (closures.has(date)) {
      const closure = closures.get(date)!;
      return { ...common, status: "closed_date", reason: `${closure.closure_type}: ${closure.reason}`, source_ids: closure.source_ids };
    }
    const session = sessions.get(date)!;
    const withSession = { ...common, session_id: session.session_id, session_type: session.session_type, source_ids: session.source_ids };
    const open = utcMs(session.open), close = utcMs(session.close);
    if (["pre_market", "post_market", "closing_auction"].includes(event.event_kind)) {
      return { ...withSession, status: "excluded_by_policy", reason: `${event.event_kind} is excluded by the package sampling policy` };
    }
    if (event.event_kind === "opening_auction" && instant !== open) {
      return { ...withSession, status: "excluded_by_policy", reason: "opening auction is eligible only at the declared open" };
    }
    if (open <= instant && instant < close) {
      return { ...withSession, status: "in_session", eligible: true, reason: "event is inside [open, close) and its kind is included" };
    }
    return { ...withSession, status: "outside_session", reason: "event is outside the declared half-open core interval" };
  });
}

export function sessionGrid(bundle: CalendarBundle, sessionDate: string, intervalMinutes: number): Record<string, any>[] {
  validateCalendar(bundle);
  if (!Number.isInteger(intervalMinutes) || intervalMinutes <= 0) throw new Error("intervalMinutes must be a positive integer");
  const session = bundle.sessions.find((row) => row.session_date === sessionDate);
  if (!session) throw new Error("no open session exists for this supported calendar date");
  const step = intervalMinutes * 60_000;
  const close = utcMs(session.close);
  const rows: Record<string, any>[] = [];
  for (let cursor = utcMs(session.open); cursor < close; ) {
    const right = Math.min(cursor + step, close);
    rows.push({
      calendar_id: bundle.calendar.calendar_id,
      calendar_version: bundle.calendar.calendar_version,
      session_id: session.session_id,
      session_date: sessionDate,
      bar_open: isoZ(cursor),
      bar_close: isoZ(right),
      is_partial: right - cursor < step,
    });
    cursor = right;
  }
  return rows;
}