@insiderfinance/totalfinance 0.1.0

package/modules/research/dist/events.js

@@ -0,0 +1,844 @@
+/**
+ * FC3 — event studies. An event study measures how an instrument's returns behave around an
+ * information instant: actual return minus a declared expected-return model, aligned on
+ * event-relative trading-session offsets.
+ *
+ * The conventions this module states (and echoes in every result's `assumptions`):
+ *
+ * - **Sessions are the data.** An instrument's trading sessions are the SORTED distinct
+ *   `tradingSessionDate` values in its return observations. Offset 0 is the event session; offset
+ *   −1 the session before it; offset +1 the one after.
+ * - **Session policy** maps `announcedTimestampMs` (converted to a UTC `YYYY-MM-DD` date) to
+ *   session 0. `'announcement-session'` anchors to the FIRST session dated ON OR AFTER the
+ *   announcement date. `'next-session'` (the default) anchors to the first session STRICTLY AFTER
+ *   the last session dated on or before the announcement date — information arriving during or
+ *   after a session is tradable the NEXT session. An announcement dated before every observed
+ *   session anchors to the first session under both policies (the information already exists when
+ *   trading begins).
+ * - **Exclusion over patching.** An event missing ANY session in its event window, or missing the
+ *   estimation window its model requires, is EXCLUDED with a per-event reason in
+ *   `diagnostics.excludedEvents` — never silently truncated or interpolated.
+ * - **Overlap is a declared choice.** `overlappingEventPolicy` is REQUIRED with no default:
+ *   `'reject'` excludes any same-instrument event whose windows collide with an earlier kept
+ *   event's (event-vs-event, event-vs-estimation, estimation-vs-event; the estimation window
+ *   participates only when the model uses one); `'allow-contaminated'` keeps every such event and
+ *   lists it in `diagnostics.contaminatedEventIds`.
+ * - **Cumulation is declared.** `'sum'` (the classic CAR, the default) adds abnormal returns;
+ *   `'compound'` chains them as Π(1 + AR) − 1. CAAR applies the SAME convention to the AAR series.
+ * - **Null with reason, never NaN.** A statistic that does not exist (t with n < 2, R² of a
+ *   zero-variance instrument) is `null` beside a written reason, never a non-finite number.
+ */
+import { requireRepresentableResult, ensureKnownKeys, ErrorCode, InputError, isoDateToEpochMs, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { requireMarketEvent, requireReturnObservations, } from './observations.js';
+// ---------------------------------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------------------------------
+const STRICT_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Shape via the regex, then the REAL calendar: `2025-02-30` must teach, never normalize. */
+const isCalendarDate = (value) => {
+    try {
+        isoDateToEpochMs(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const WINDOW_KEYS = ['startTradingSessionOffset', 'endTradingSessionOffset'];
+const MARKET_RETURN_KEYS = ['tradingSessionDate', 'simpleReturn'];
+const SESSION_POLICIES = [
+    'announcement-session',
+    'next-session',
+];
+const OVERLAP_POLICIES = ['reject', 'allow-contaminated'];
+const CUMULATIVE_CONVENTIONS = ['sum', 'compound'];
+const MODEL_NAMES = ['mean-adjusted', 'market-adjusted', 'market', 'custom'];
+const EVENT_STUDY_EXAMPLE = "eventStudy({ events: [{ eventId: 'e1', instrumentId: 'AAA', eventType: 'earnings', announcedTimestampMs: 1709823600000 }], returnObservations: [{ instrumentId: 'AAA', tradingSessionDate: '2024-03-07', simpleReturn: 0.012 }, …], eventWindow: { startTradingSessionOffset: -1, endTradingSessionOffset: 1 }, estimationWindow: { startTradingSessionOffset: -6, endTradingSessionOffset: -2 }, expectedReturnModel: { model: 'mean-adjusted' }, overlappingEventPolicy: 'reject' })";
+/** Validate the event list: each a {@link MarketEvent}, identities unique. */
+function requireEvents(functionName, events) {
+    if (!Array.isArray(events) || events.length === 0) {
+        throw new InputError(`${functionName}: events must be a non-empty array of market events — an event study needs at least one event.\n  e.g. ${EVENT_STUDY_EXAMPLE}`, { code: ErrorCode.InputOutOfRange, context: { field: 'events' } });
+    }
+    const seen = new Set();
+    events.forEach((event, index) => {
+        requireMarketEvent(functionName, `events[${index}]`, event);
+        if (seen.has(event.eventId)) {
+            throw new InputError(`${functionName}: events[${index}] reuses eventId '${event.eventId}' — event identities must be unique so per-event exclusions and contamination lists are unambiguous.`, { code: ErrorCode.InputOutOfRange, context: { field: `events[${index}].eventId` } });
+        }
+        seen.add(event.eventId);
+    });
+}
+/** Validate an inclusive session window: integer offsets, start ≤ end. */
+function requireSessionWindow(functionName, field, window) {
+    requireArgumentObject(functionName, field, window);
+    ensureKnownKeys(functionName, field, window, WINDOW_KEYS);
+    for (const key of WINDOW_KEYS) {
+        const value = window[key];
+        if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+            throw new InputError(`${functionName}: ${field}.${key} must be an integer trading-session offset (offset 0 is the event session). Received ${value === null ? 'null' : typeof value === 'number' ? String(value) : typeof value}.\n  e.g. ${functionName}({ ..., ${field}: { startTradingSessionOffset: -1, endTradingSessionOffset: 1 } })`, { code: ErrorCode.InputWrongType, context: { field: `${field}.${key}` } });
+        }
+    }
+    if (window.startTradingSessionOffset > window.endTradingSessionOffset) {
+        throw new InputError(`${functionName}: ${field}.startTradingSessionOffset (${window.startTradingSessionOffset}) must be ≤ ${field}.endTradingSessionOffset (${window.endTradingSessionOffset}) — the window is inclusive and reads left to right.`, { code: ErrorCode.InputOutOfRange, context: { field } });
+    }
+}
+/** Validate the model union and return the string classified for `assumptions`. */
+function requireExpectedReturnModel(functionName, model) {
+    requireArgumentObject(functionName, 'expectedReturnModel', model);
+    if (!MODEL_NAMES.includes(model.model)) {
+        throw new InputError(`${functionName}: expectedReturnModel.model must be one of ${MODEL_NAMES.map((name) => `'${name}'`).join(', ')}. Received ${model.model === null ? 'null' : JSON.stringify(model.model)}.\n  e.g. ${functionName}({ ..., expectedReturnModel: { model: 'mean-adjusted' } })`, { code: ErrorCode.InputInvalidEnum, context: { field: 'expectedReturnModel.model' } });
+    }
+    if (model.model === 'custom') {
+        ensureKnownKeys(functionName, 'expectedReturnModel', model, ['model', 'expectedReturn']);
+        if (typeof model.expectedReturn !== 'function') {
+            throw new InputError(`${functionName}: expectedReturnModel.expectedReturn must be a function (context) => number when model is 'custom' — the structural escape hatch for caller factor models.\n  e.g. ${functionName}({ ..., expectedReturnModel: { model: 'custom', expectedReturn: ({ marketReturn }) => 0.0002 + 1.1 * (marketReturn ?? 0) } })`, {
+                code: ErrorCode.InputWrongType,
+                context: { field: 'expectedReturnModel.expectedReturn' },
+            });
+        }
+        return 'custom (non-serializable)';
+    }
+    ensureKnownKeys(functionName, 'expectedReturnModel', model, ['model']);
+    return model.model;
+}
+/** Validate an enum-typed option when present; return the documented default when absent. */
+function resolveEnumOption(functionName, field, value, allowed, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (!allowed.includes(value)) {
+        throw new InputError(`${functionName}: ${field} must be one of ${allowed.map((name) => `'${name}'`).join(' | ')}. Received ${value === null ? 'null' : JSON.stringify(value)}.`, { code: ErrorCode.InputInvalidEnum, context: { field } });
+    }
+    return value;
+}
+/** Index return observations by instrument, refusing ambiguous duplicate sessions. */
+function buildInstrumentSessions(functionName, observations) {
+    const byInstrument = new Map();
+    observations.forEach((row, index) => {
+        let entry = byInstrument.get(row.instrumentId);
+        if (entry === undefined) {
+            entry = { dates: [], returnByDate: new Map() };
+            byInstrument.set(row.instrumentId, entry);
+        }
+        if (entry.returnByDate.has(row.tradingSessionDate)) {
+            throw new InputError(`${functionName}: returnObservations[${index}] duplicates instrument '${row.instrumentId}' session ${row.tradingSessionDate} — one return per instrument per trading session; two rows for the same session are ambiguous.`, { code: ErrorCode.InputOutOfRange, context: { field: `returnObservations[${index}]` } });
+        }
+        entry.returnByDate.set(row.tradingSessionDate, row.simpleReturn);
+    });
+    for (const entry of byInstrument.values()) {
+        entry.dates = [...entry.returnByDate.keys()].sort();
+    }
+    return byInstrument;
+}
+/** Validate market returns and index them by date, refusing duplicates. */
+function buildMarketReturnIndex(functionName, rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new InputError(`${functionName}: marketReturns must be a non-empty array of { tradingSessionDate, simpleReturn } rows.\n  e.g. ${functionName}({ ..., marketReturns: [{ tradingSessionDate: '2024-03-01', simpleReturn: 0.0012 }] })`, { code: ErrorCode.InputOutOfRange, context: { field: 'marketReturns' } });
+    }
+    const byDate = new Map();
+    rows.forEach((row, index) => {
+        const path = `marketReturns[${index}]`;
+        requireArgumentObject(functionName, path, row);
+        ensureKnownKeys(functionName, path, row, MARKET_RETURN_KEYS);
+        if (typeof row.tradingSessionDate !== 'string' ||
+            !STRICT_DATE.test(row.tradingSessionDate) ||
+            !isCalendarDate(row.tradingSessionDate)) {
+            throw new InputError(`${functionName}: ${path}.tradingSessionDate must be a strict YYYY-MM-DD calendar date. Received ${row.tradingSessionDate === null ? 'null' : JSON.stringify(row.tradingSessionDate)}.`, { code: ErrorCode.InputWrongType, context: { field: `${path}.tradingSessionDate` } });
+        }
+        requireFiniteFields(functionName, row, ['simpleReturn'], {
+            exampleCall: () => `${functionName}({ ..., marketReturns: [{ tradingSessionDate: '2024-03-01', simpleReturn: 0.0012 }] })`,
+            path,
+        });
+        if (byDate.has(row.tradingSessionDate)) {
+            throw new InputError(`${functionName}: ${path} duplicates the market return for session ${row.tradingSessionDate} — one market return per trading session.`, { code: ErrorCode.InputOutOfRange, context: { field: path } });
+        }
+        byDate.set(row.tradingSessionDate, row.simpleReturn);
+    });
+    return byDate;
+}
+// ---------------------------------------------------------------------------------------------------
+// Anchoring — ONE implementation, shared by eventStudy and alignEventWindows
+// ---------------------------------------------------------------------------------------------------
+/** Convert an epoch-ms instant to its UTC `YYYY-MM-DD` trading-comparison date. */
+function utcDateOf(functionName, field, timestampMs) {
+    const instant = new Date(timestampMs);
+    if (Number.isNaN(instant.getTime())) {
+        throw new InputError(`${functionName}: ${field} (${timestampMs}) is outside the representable date range — epoch milliseconds were expected.`, { code: ErrorCode.InputOutOfRange, context: { field } });
+    }
+    const iso = instant.toISOString();
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(iso)) {
+        throw new InputError(`${functionName}: ${field} (${timestampMs}) resolves outside years 0000–9999 (${iso}) — trading-session dates are strict YYYY-MM-DD.`, { code: ErrorCode.InputOutOfRange, context: { field } });
+    }
+    return iso.slice(0, 10);
+}
+/**
+ * Anchor session 0 on an instrument's sorted sessions.
+ *
+ * - `'announcement-session'`: the FIRST session dated ≥ the announcement date.
+ * - `'next-session'`: the first session STRICTLY AFTER the last session dated ≤ the announcement
+ *   date; when no session is dated ≤ it, the first session (the information predates trading).
+ */
+function resolveAnchorIndex(dates, announcementDate, sessionPolicy) {
+    if (sessionPolicy === 'announcement-session') {
+        for (let i = 0; i < dates.length; i++) {
+            if (dates[i] >= announcementDate)
+                return { ok: true, anchorIndex: i };
+        }
+        return {
+            ok: false,
+            reason: `no trading session on or after the announcement date ${announcementDate} — 'announcement-session' anchors session 0 to the first session dated on or after the announcement date.`,
+        };
+    }
+    let lastAtOrBefore = -1;
+    for (let i = 0; i < dates.length; i++) {
+        if (dates[i] <= announcementDate)
+            lastAtOrBefore = i;
+        else
+            break;
+    }
+    if (lastAtOrBefore === -1)
+        return { ok: true, anchorIndex: 0 };
+    const anchorIndex = lastAtOrBefore + 1;
+    if (anchorIndex >= dates.length) {
+        return {
+            ok: false,
+            reason: `the announcement date ${announcementDate} is on or after the last observed session (${dates[dates.length - 1]}) — 'next-session' anchors session 0 to the first session strictly after the last session dated on or before the announcement, and no later session exists in the data.`,
+        };
+    }
+    return { ok: true, anchorIndex };
+}
+/** Slice an inclusive offset window from the sorted sessions, or say exactly what is missing. */
+function sliceSessionWindow(index, anchorIndex, window, windowLabel) {
+    const rows = [];
+    for (let offset = window.startTradingSessionOffset; offset <= window.endTradingSessionOffset; offset++) {
+        const sessionIndex = anchorIndex + offset;
+        if (sessionIndex < 0 || sessionIndex >= index.dates.length) {
+            return {
+                ok: false,
+                reason: `missing trading session at ${windowLabel} offset ${offset >= 0 ? `+${offset}` : String(offset)} relative to anchor session ${index.dates[anchorIndex]} — the instrument's observed sessions span ${index.dates[0]}..${index.dates[index.dates.length - 1]}.`,
+            };
+        }
+        const tradingSessionDate = index.dates[sessionIndex];
+        rows.push({
+            tradingSessionOffset: offset,
+            tradingSessionDate,
+            simpleReturn: index.returnByDate.get(tradingSessionDate),
+        });
+    }
+    return { ok: true, rows };
+}
+/** The single anchoring code path: date the announcement, anchor session 0, slice the window. */
+function alignEventToSessions(functionName, event, eventField, sessionsByInstrument, eventWindow, sessionPolicy) {
+    const announcementDate = utcDateOf(functionName, `${eventField}.announcedTimestampMs`, event.announcedTimestampMs);
+    const index = sessionsByInstrument.get(event.instrumentId);
+    if (index === undefined) {
+        return {
+            ok: false,
+            reason: `no return observations were supplied for instrument '${event.instrumentId}'.`,
+        };
+    }
+    const anchor = resolveAnchorIndex(index.dates, announcementDate, sessionPolicy);
+    if (!anchor.ok)
+        return anchor;
+    const slice = sliceSessionWindow(index, anchor.anchorIndex, eventWindow, 'event window');
+    if (!slice.ok)
+        return slice;
+    return {
+        ok: true,
+        anchorIndex: anchor.anchorIndex,
+        anchorTradingSessionDate: index.dates[anchor.anchorIndex],
+        rows: slice.rows,
+    };
+}
+// ---------------------------------------------------------------------------------------------------
+// Statistics
+// ---------------------------------------------------------------------------------------------------
+/** Cumulate a series under the declared convention: running Σ, or running Π(1 + v) − 1. */
+function cumulate(values, convention) {
+    const out = [];
+    if (convention === 'sum') {
+        let total = 0;
+        for (const value of values) {
+            total += value;
+            out.push(total);
+        }
+    }
+    else {
+        let factor = 1;
+        for (const value of values) {
+            factor *= 1 + value;
+            out.push(factor - 1);
+        }
+    }
+    return out;
+}
+/** `t = mean / (sampleStandardDeviation / √n)`; null-with-reason for n < 2 or zero variance. */
+function crossSectionalTest(values) {
+    const n = values.length;
+    let sum = 0;
+    for (const value of values)
+        sum += value;
+    const mean = sum / n;
+    if (n < 2) {
+        return {
+            mean,
+            tStatistic: null,
+            tStatisticAbsentReason: `the cross-sectional t-statistic needs at least 2 events; received n=${n}.`,
+        };
+    }
+    let sumOfSquares = 0;
+    for (const value of values)
+        sumOfSquares += (value - mean) * (value - mean);
+    const sampleStandardDeviation = Math.sqrt(sumOfSquares / (n - 1));
+    if (sampleStandardDeviation === 0) {
+        return {
+            mean,
+            tStatistic: null,
+            tStatisticAbsentReason: `zero cross-sectional variance across the ${n} events at this offset — the t-statistic is undefined, never ±Infinity.`,
+        };
+    }
+    return { mean, tStatistic: mean / (sampleStandardDeviation / Math.sqrt(n)) };
+}
+/** Plain-sums OLS of instrument returns on market returns over the estimation window. */
+function fitMarketModel(marketSeries, instrumentSeries) {
+    const n = marketSeries.length;
+    let sumX = 0;
+    let sumY = 0;
+    for (let i = 0; i < n; i++) {
+        sumX += marketSeries[i];
+        sumY += instrumentSeries[i];
+    }
+    const meanX = sumX / n;
+    const meanY = sumY / n;
+    let sumXX = 0;
+    let sumXY = 0;
+    let sumYY = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = marketSeries[i] - meanX;
+        const dy = instrumentSeries[i] - meanY;
+        sumXX += dx * dx;
+        sumXY += dx * dy;
+        sumYY += dy * dy;
+    }
+    if (sumXX === 0) {
+        return {
+            ok: false,
+            reason: `market model inestimable: market returns are constant across the ${n}-session estimation window (zero variance), so beta is undefined.`,
+        };
+    }
+    const beta = sumXY / sumXX;
+    const alpha = meanY - beta * meanX;
+    if (sumYY === 0) {
+        return {
+            ok: true,
+            model: {
+                alpha,
+                beta,
+                rSquared: null,
+                rSquaredAbsentReason: 'instrument returns are constant across the estimation window — the explained share of zero variance is undefined, so R² is null with this reason, never NaN.',
+            },
+        };
+    }
+    return { ok: true, model: { alpha, beta, rSquared: (sumXY * sumXY) / (sumXX * sumYY) } };
+}
+/** Build the per-offset AAR/CAAR/t rows shared by {@link eventStudy} and the aggregator. */
+function buildAverageAbnormalReturns(events, eventWindow, convention, warnings, emptyWarning) {
+    if (events.length === 0) {
+        warnings.push(emptyWarning);
+        return [];
+    }
+    const offsetCount = eventWindow.endTradingSessionOffset - eventWindow.startTradingSessionOffset + 1;
+    const tests = [];
+    const averages = [];
+    for (let k = 0; k < offsetCount; k++) {
+        const values = events.map((event) => event.rows[k].abnormalReturn);
+        const test = crossSectionalTest(values);
+        tests.push(test);
+        averages.push(test.mean);
+    }
+    const cumulativeAverages = cumulate(averages, convention);
+    return tests.map((test, k) => ({
+        tradingSessionOffset: eventWindow.startTradingSessionOffset + k,
+        averageAbnormalReturn: test.mean,
+        cumulativeAverageAbnormalReturn: cumulativeAverages[k],
+        eventCount: events.length,
+        tStatistic: test.tStatistic,
+        ...(test.tStatisticAbsentReason !== undefined
+            ? { tStatisticAbsentReason: test.tStatisticAbsentReason }
+            : {}),
+    }));
+}
+function spansOverlap(a, b) {
+    return a[0] <= b[1] && b[0] <= a[1];
+}
+function spansOf(candidate, eventWindow, estimationWindow) {
+    const eventSpan = [
+        candidate.anchorIndex + eventWindow.startTradingSessionOffset,
+        candidate.anchorIndex + eventWindow.endTradingSessionOffset,
+    ];
+    if (estimationWindow === undefined)
+        return { eventSpan };
+    return {
+        eventSpan,
+        estimationSpan: [
+            candidate.anchorIndex + estimationWindow.startTradingSessionOffset,
+            candidate.anchorIndex + estimationWindow.endTradingSessionOffset,
+        ],
+    };
+}
+/**
+ * A pair conflicts when an EVENT window intrudes anywhere abnormal behaviour must not: the other
+ * event's event window, or the estimation window a model fits on. Two estimation windows sharing
+ * history do NOT conflict — only an event period inside them contaminates.
+ */
+function candidatesConflict(a, b) {
+    if (spansOverlap(a.eventSpan, b.eventSpan))
+        return true;
+    if (b.estimationSpan !== undefined && spansOverlap(a.eventSpan, b.estimationSpan))
+        return true;
+    if (a.estimationSpan !== undefined && spansOverlap(a.estimationSpan, b.eventSpan))
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------------------------------
+// eventStudy
+// ---------------------------------------------------------------------------------------------------
+const EVENT_STUDY_KEYS = [
+    'events',
+    'returnObservations',
+    'marketReturns',
+    'eventWindow',
+    'estimationWindow',
+    'expectedReturnModel',
+    'sessionPolicy',
+    'overlappingEventPolicy',
+    'cumulativeConvention',
+];
+/**
+ * Run an event study: anchor each event on its instrument's sessions under the declared session
+ * policy, model expected returns, and disclose abnormal returns per event and across events.
+ * Every convention is echoed in `assumptions`; every dropped event is named with its reason in
+ * `diagnostics.excludedEvents` — see the module header for the exact anchoring and overlap rules.
+ */
+export function eventStudy(input) {
+    const functionName = 'eventStudy';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, EVENT_STUDY_KEYS);
+    requireEvents(functionName, input.events);
+    requireReturnObservations(functionName, 'returnObservations', input.returnObservations);
+    requireSessionWindow(functionName, 'eventWindow', input.eventWindow);
+    const modelLabel = requireExpectedReturnModel(functionName, input.expectedReturnModel);
+    const model = input.expectedReturnModel;
+    const needsEstimation = model.model === 'mean-adjusted' || model.model === 'market';
+    const needsMarket = model.model === 'market-adjusted' || model.model === 'market';
+    const sessionPolicy = resolveEnumOption(functionName, 'sessionPolicy', input.sessionPolicy, SESSION_POLICIES, 'next-session');
+    const cumulativeConvention = resolveEnumOption(functionName, 'cumulativeConvention', input.cumulativeConvention, CUMULATIVE_CONVENTIONS, 'sum');
+    if (input.overlappingEventPolicy === undefined) {
+        throw new InputError(`${functionName}: overlappingEventPolicy is required and has NO default — 'reject' excludes same-instrument events whose windows overlap; 'allow-contaminated' keeps them and lists them in diagnostics.contaminatedEventIds. Overlap handling changes the statistics, so the caller must choose.\n  e.g. ${EVENT_STUDY_EXAMPLE}`, { code: ErrorCode.InputMissingField, context: { field: 'overlappingEventPolicy' } });
+    }
+    const overlappingEventPolicy = resolveEnumOption(functionName, 'overlappingEventPolicy', input.overlappingEventPolicy, OVERLAP_POLICIES, 'reject');
+    const warnings = [];
+    if (input.estimationWindow !== undefined) {
+        requireSessionWindow(functionName, 'estimationWindow', input.estimationWindow);
+        if (input.estimationWindow.endTradingSessionOffset >= input.eventWindow.startTradingSessionOffset) {
+            throw new InputError(`${functionName}: estimationWindow.endTradingSessionOffset (${input.estimationWindow.endTradingSessionOffset}) must end strictly BEFORE eventWindow.startTradingSessionOffset (${input.eventWindow.startTradingSessionOffset}) — a model estimated through the event window measures the event twice.\n  e.g. ${functionName}({ ..., estimationWindow: { startTradingSessionOffset: -6, endTradingSessionOffset: -2 }, eventWindow: { startTradingSessionOffset: -1, endTradingSessionOffset: 1 } })`, { code: ErrorCode.InputOutOfRange, context: { field: 'estimationWindow' } });
+        }
+        if (!needsEstimation) {
+            warnings.push(`estimationWindow was supplied but the '${model.model}' model does not use one — it is echoed in assumptions and does not participate in overlap detection.`);
+        }
+        else if (input.estimationWindow.endTradingSessionOffset >= 0) {
+            warnings.push('estimationWindow includes sessions at or after the event session (offset 0) — an expected-return model estimated on post-announcement sessions is contaminated by the event itself.');
+        }
+    }
+    else if (needsEstimation) {
+        throw new InputError(`${functionName}: the '${model.model}' model estimates expected returns over a pre-event window — supply estimationWindow (integers, ending strictly before the event window starts).\n  e.g. ${EVENT_STUDY_EXAMPLE}`, { code: ErrorCode.InputMissingField, context: { field: 'estimationWindow' } });
+    }
+    let marketByDate;
+    if (input.marketReturns !== undefined) {
+        marketByDate = buildMarketReturnIndex(functionName, input.marketReturns);
+        if (model.model === 'mean-adjusted') {
+            warnings.push("marketReturns were supplied but the 'mean-adjusted' model does not use them.");
+        }
+    }
+    else if (needsMarket) {
+        throw new InputError(`${functionName}: the '${model.model}' model needs same-session market returns — supply marketReturns as [{ tradingSessionDate, simpleReturn }].\n  e.g. ${functionName}({ ..., marketReturns: [{ tradingSessionDate: '2024-03-01', simpleReturn: 0.0012 }], expectedReturnModel: { model: '${model.model}' } })`, { code: ErrorCode.InputMissingField, context: { field: 'marketReturns' } });
+    }
+    const sessionsByInstrument = buildInstrumentSessions(functionName, input.returnObservations);
+    // -- Per-event alignment and data-completeness (exclusion with reason, never patching) ----------
+    const excludedEvents = [];
+    const candidates = [];
+    input.events.forEach((event, index) => {
+        const exclude = (reason) => {
+            excludedEvents.push({ eventId: event.eventId, reason });
+        };
+        const alignment = alignEventToSessions(functionName, event, `events[${index}]`, sessionsByInstrument, input.eventWindow, sessionPolicy);
+        if (!alignment.ok) {
+            exclude(alignment.reason);
+            return;
+        }
+        const index2 = sessionsByInstrument.get(event.instrumentId);
+        let estimationRows;
+        if (needsEstimation) {
+            const slice = sliceSessionWindow(index2, alignment.anchorIndex, input.estimationWindow, 'estimation window');
+            if (!slice.ok) {
+                exclude(slice.reason);
+                return;
+            }
+            estimationRows = slice.rows;
+        }
+        if (needsMarket) {
+            const rowsNeedingMarket = model.model === 'market' ? [...estimationRows, ...alignment.rows] : alignment.rows;
+            for (const row of rowsNeedingMarket) {
+                if (!marketByDate.has(row.tradingSessionDate)) {
+                    exclude(`no market return was supplied for session ${row.tradingSessionDate} — the '${model.model}' model needs the same-session market return for every event-window${model.model === 'market' ? ' and estimation-window' : ''} session.`);
+                    return;
+                }
+            }
+        }
+        let marketModel;
+        if (model.model === 'market') {
+            const fit = fitMarketModel(estimationRows.map((row) => marketByDate.get(row.tradingSessionDate)), estimationRows.map((row) => row.simpleReturn));
+            if (!fit.ok) {
+                exclude(fit.reason);
+                return;
+            }
+            marketModel = fit.model;
+            if (fit.model.rSquaredAbsentReason !== undefined) {
+                warnings.push(`event '${event.eventId}': ${fit.model.rSquaredAbsentReason}`);
+            }
+        }
+        candidates.push({
+            event,
+            anchorIndex: alignment.anchorIndex,
+            anchorTradingSessionDate: alignment.anchorTradingSessionDate,
+            eventRows: alignment.rows,
+            ...(estimationRows !== undefined ? { estimationRows } : {}),
+            ...(marketModel !== undefined ? { marketModel } : {}),
+        });
+    });
+    // -- Overlap policy (same-instrument only; estimation windows participate when the model uses one)
+    const effectiveEstimationWindow = needsEstimation ? input.estimationWindow : undefined;
+    const contaminatedEventIds = [];
+    const rejectedEventIds = new Set();
+    const byInstrument = new Map();
+    for (const candidate of candidates) {
+        const group = byInstrument.get(candidate.event.instrumentId);
+        if (group === undefined)
+            byInstrument.set(candidate.event.instrumentId, [candidate]);
+        else
+            group.push(candidate);
+    }
+    for (const group of byInstrument.values()) {
+        const sorted = [...group].sort((a, b) => a.anchorIndex - b.anchorIndex ||
+            a.event.announcedTimestampMs - b.event.announcedTimestampMs ||
+            (a.event.eventId < b.event.eventId ? -1 : 1));
+        if (overlappingEventPolicy === 'reject') {
+            const kept = [];
+            for (const candidate of sorted) {
+                const spans = spansOf(candidate, input.eventWindow, effectiveEstimationWindow);
+                const collision = kept.find((entry) => candidatesConflict(spans, entry.spans));
+                if (collision !== undefined) {
+                    rejectedEventIds.add(candidate.event.eventId);
+                    excludedEvents.push({
+                        eventId: candidate.event.eventId,
+                        reason: `overlappingEventPolicy 'reject': its event window (${candidate.eventRows[0].tradingSessionDate}..${candidate.eventRows[candidate.eventRows.length - 1].tradingSessionDate}) overlaps the ${effectiveEstimationWindow !== undefined ? 'event or estimation window' : 'event window'} of event '${collision.candidate.event.eventId}' on the same instrument — choose 'allow-contaminated' to keep and disclose contaminated events.`,
+                    });
+                }
+                else {
+                    kept.push({ candidate, spans });
+                }
+            }
+        }
+        else {
+            const spans = sorted.map((candidate) => spansOf(candidate, input.eventWindow, effectiveEstimationWindow));
+            const contaminated = new Set();
+            for (let i = 0; i < sorted.length; i++) {
+                for (let j = i + 1; j < sorted.length; j++) {
+                    if (candidatesConflict(spans[i], spans[j])) {
+                        contaminated.add(i);
+                        contaminated.add(j);
+                    }
+                }
+            }
+            for (let i = 0; i < sorted.length; i++) {
+                if (contaminated.has(i))
+                    contaminatedEventIds.push(sorted[i].event.eventId);
+            }
+        }
+    }
+    const included = candidates.filter((candidate) => !rejectedEventIds.has(candidate.event.eventId));
+    // -- Expected returns, abnormal returns, and cumulation -----------------------------------------
+    const eventResults = included.map((candidate) => {
+        let estimationMean = 0;
+        if (model.model === 'mean-adjusted') {
+            let sum = 0;
+            for (const row of candidate.estimationRows)
+                sum += row.simpleReturn;
+            estimationMean = sum / candidate.estimationRows.length;
+        }
+        const rows = candidate.eventRows.map((row) => {
+            let expectedReturn;
+            if (model.model === 'mean-adjusted') {
+                expectedReturn = estimationMean;
+            }
+            else if (model.model === 'market-adjusted') {
+                expectedReturn = marketByDate.get(row.tradingSessionDate);
+            }
+            else if (model.model === 'market') {
+                expectedReturn =
+                    candidate.marketModel.alpha +
+                        candidate.marketModel.beta * marketByDate.get(row.tradingSessionDate);
+            }
+            else {
+                const marketReturn = marketByDate?.get(row.tradingSessionDate);
+                expectedReturn = model.expectedReturn({
+                    instrumentId: candidate.event.instrumentId,
+                    tradingSessionDate: row.tradingSessionDate,
+                    ...(marketReturn !== undefined ? { marketReturn } : {}),
+                });
+                if (typeof expectedReturn !== 'number' || !Number.isFinite(expectedReturn)) {
+                    throw new InputError(`${functionName}: expectedReturnModel.expectedReturn returned ${expectedReturn === null ? 'null' : typeof expectedReturn === 'number' ? String(expectedReturn) : typeof expectedReturn} for instrument '${candidate.event.instrumentId}' at ${row.tradingSessionDate} — a structural factor model must return a finite decimal return for every session it is asked about.`, {
+                        code: ErrorCode.InputWrongType,
+                        context: { field: 'expectedReturnModel.expectedReturn' },
+                    });
+                }
+            }
+            return {
+                tradingSessionOffset: row.tradingSessionOffset,
+                tradingSessionDate: row.tradingSessionDate,
+                actualReturn: row.simpleReturn,
+                expectedReturn,
+                abnormalReturn: row.simpleReturn - expectedReturn,
+            };
+        });
+        const cumulative = cumulate(rows.map((row) => row.abnormalReturn), cumulativeConvention);
+        return {
+            eventId: candidate.event.eventId,
+            instrumentId: candidate.event.instrumentId,
+            anchorTradingSessionDate: candidate.anchorTradingSessionDate,
+            ...(candidate.marketModel !== undefined ? { marketModel: candidate.marketModel } : {}),
+            rows,
+            cumulativeAbnormalReturn: cumulative[cumulative.length - 1],
+        };
+    });
+    const averageAbnormalReturns = buildAverageAbnormalReturns(eventResults, input.eventWindow, cumulativeConvention, warnings, 'no events were included — average abnormal returns are empty; diagnostics.excludedEvents carries the per-event reasons.');
+    return requireRepresentableResult('eventStudy', {
+        assumptions: {
+            sessionPolicy,
+            cumulativeConvention,
+            expectedReturnModel: modelLabel,
+            eventWindow: {
+                startTradingSessionOffset: input.eventWindow.startTradingSessionOffset,
+                endTradingSessionOffset: input.eventWindow.endTradingSessionOffset,
+            },
+            ...(input.estimationWindow !== undefined
+                ? {
+                    estimationWindow: {
+                        startTradingSessionOffset: input.estimationWindow.startTradingSessionOffset,
+                        endTradingSessionOffset: input.estimationWindow.endTradingSessionOffset,
+                    },
+                }
+                : {}),
+            overlappingEventPolicy,
+        },
+        diagnostics: {
+            warnings,
+            eventsSupplied: input.events.length,
+            eventsIncluded: eventResults.length,
+            excludedEvents,
+            contaminatedEventIds,
+        },
+        events: eventResults,
+        averageAbnormalReturns,
+    });
+}
+// ---------------------------------------------------------------------------------------------------
+// aggregateEventStudies
+// ---------------------------------------------------------------------------------------------------
+const AGGREGATE_KEYS = ['studies'];
+const RESULT_KEYS = ['assumptions', 'diagnostics', 'events', 'averageAbnormalReturns'];
+function formatWindow(window) {
+    return `[${window.startTradingSessionOffset}, ${window.endTradingSessionOffset}]`;
+}
+function requireSharedAssumption(index, field, value, reference, why) {
+    if (value !== reference) {
+        throw new InputError(`aggregateEventStudies: studies[${index}].assumptions.${field} (${value}) does not match studies[0].assumptions.${field} (${reference}) — ${why}`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: `studies[${index}].assumptions.${field}` },
+        });
+    }
+}
+/**
+ * Pool the INCLUDED events of several {@link eventStudy} results and recompute AAR/CAAR and
+ * per-offset t-statistics across the pooled cross-section. Studies must share `sessionPolicy`,
+ * `cumulativeConvention`, and `eventWindow` — pooled per-offset statistics are meaningless
+ * otherwise, and a mismatch is refused naming both values.
+ */
+export function aggregateEventStudies(input) {
+    const functionName = 'aggregateEventStudies';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, AGGREGATE_KEYS);
+    if (!Array.isArray(input.studies) || input.studies.length === 0) {
+        throw new InputError(`${functionName}: studies must be a non-empty array of eventStudy results.\n  e.g. aggregateEventStudies({ studies: [studyA, studyB] })`, { code: ErrorCode.InputOutOfRange, context: { field: 'studies' } });
+    }
+    const studies = input.studies;
+    studies.forEach((study, index) => {
+        const path = `studies[${index}]`;
+        requireArgumentObject(functionName, path, study);
+        for (const key of RESULT_KEYS) {
+            if (study[key] === undefined) {
+                throw new InputError(`${functionName}: ${path} is not an eventStudy result — it must carry assumptions, diagnostics, events, and averageAbnormalReturns.`, { code: ErrorCode.InputMissingField, context: { field: `${path}.${key}` } });
+            }
+        }
+    });
+    const first = studies[0];
+    const eventWindow = first.assumptions.eventWindow;
+    studies.forEach((study, index) => {
+        if (index === 0)
+            return;
+        requireSharedAssumption(index, 'sessionPolicy', `'${study.assumptions.sessionPolicy}'`, `'${first.assumptions.sessionPolicy}'`, 'pooled offsets are only comparable under one anchoring policy.');
+        requireSharedAssumption(index, 'cumulativeConvention', `'${study.assumptions.cumulativeConvention}'`, `'${first.assumptions.cumulativeConvention}'`, 'pooled CAR/CAAR under two cumulation conventions is not one statistic.');
+        requireSharedAssumption(index, 'eventWindow', formatWindow(study.assumptions.eventWindow), formatWindow(eventWindow), 'pooled per-offset statistics need one shared event window.');
+    });
+    // -- Pool the included events and verify each covers the shared window --------------------------
+    const offsetCount = eventWindow.endTradingSessionOffset - eventWindow.startTradingSessionOffset + 1;
+    const pooledEvents = [];
+    studies.forEach((study, studyIndex) => {
+        study.events.forEach((event, eventIndex) => {
+            if (event.rows.length !== offsetCount) {
+                throw new InputError(`${functionName}: studies[${studyIndex}].events[${eventIndex}] ('${event.eventId}') carries ${event.rows.length} rows but the shared event window ${formatWindow(eventWindow)} spans ${offsetCount} sessions — aggregate over unmodified eventStudy results.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { field: `studies[${studyIndex}].events[${eventIndex}].rows` },
+                });
+            }
+            event.rows.forEach((row, k) => {
+                const expectedOffset = eventWindow.startTradingSessionOffset + k;
+                if (row.tradingSessionOffset !== expectedOffset) {
+                    throw new InputError(`${functionName}: studies[${studyIndex}].events[${eventIndex}].rows[${k}] is at offset ${row.tradingSessionOffset}, expected ${expectedOffset} — aggregate over unmodified eventStudy results.`, {
+                        code: ErrorCode.InputOutOfRange,
+                        context: { field: `studies[${studyIndex}].events[${eventIndex}].rows[${k}]` },
+                    });
+                }
+            });
+            pooledEvents.push(event);
+        });
+    });
+    // -- Union the diagnostics ----------------------------------------------------------------------
+    const warnings = [];
+    const seenWarnings = new Set();
+    for (const study of studies) {
+        for (const warning of study.diagnostics.warnings) {
+            if (!seenWarnings.has(warning)) {
+                seenWarnings.add(warning);
+                warnings.push(warning);
+            }
+        }
+    }
+    const idCounts = new Map();
+    for (const event of pooledEvents) {
+        idCounts.set(event.eventId, (idCounts.get(event.eventId) ?? 0) + 1);
+    }
+    const duplicatedIds = [...idCounts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([eventId]) => eventId);
+    if (duplicatedIds.length > 0) {
+        warnings.push(`events ${duplicatedIds.map((eventId) => `'${eventId}'`).join(', ')} appear in more than one study — pooled statistics count them once per appearance.`);
+    }
+    const models = [...new Set(studies.map((study) => study.assumptions.expectedReturnModel))];
+    const overlapPolicies = [
+        ...new Set(studies.map((study) => study.assumptions.overlappingEventPolicy)),
+    ];
+    const estimationWindows = studies.map((study) => study.assumptions.estimationWindow);
+    const firstEstimation = estimationWindows[0];
+    const estimationShared = estimationWindows.every((window) => window === undefined
+        ? firstEstimation === undefined
+        : firstEstimation !== undefined &&
+            window.startTradingSessionOffset === firstEstimation.startTradingSessionOffset &&
+            window.endTradingSessionOffset === firstEstimation.endTradingSessionOffset);
+    if (!estimationShared) {
+        warnings.push('studies declare differing estimation windows — the aggregate omits estimationWindow from its assumptions; each pooled event keeps the model its own study fitted.');
+    }
+    const averageAbnormalReturns = buildAverageAbnormalReturns(pooledEvents, eventWindow, first.assumptions.cumulativeConvention, warnings, 'no events were included in any study — pooled average abnormal returns are empty.');
+    return {
+        assumptions: {
+            sessionPolicy: first.assumptions.sessionPolicy,
+            cumulativeConvention: first.assumptions.cumulativeConvention,
+            expectedReturnModel: models.length === 1 ? models[0] : `mixed (${models.join(', ')})`,
+            eventWindow: {
+                startTradingSessionOffset: eventWindow.startTradingSessionOffset,
+                endTradingSessionOffset: eventWindow.endTradingSessionOffset,
+            },
+            ...(estimationShared && firstEstimation !== undefined
+                ? {
+                    estimationWindow: {
+                        startTradingSessionOffset: firstEstimation.startTradingSessionOffset,
+                        endTradingSessionOffset: firstEstimation.endTradingSessionOffset,
+                    },
+                }
+                : {}),
+            overlappingEventPolicy: overlapPolicies.length === 1 ? overlapPolicies[0] : 'mixed',
+        },
+        diagnostics: {
+            warnings,
+            eventsSupplied: studies.reduce((total, study) => total + study.diagnostics.eventsSupplied, 0),
+            eventsIncluded: pooledEvents.length,
+            excludedEvents: studies.flatMap((study) => study.diagnostics.excludedEvents),
+            contaminatedEventIds: [
+                ...new Set(studies.flatMap((study) => study.diagnostics.contaminatedEventIds)),
+            ],
+        },
+        events: pooledEvents,
+        averageAbnormalReturns,
+        studiesAggregated: studies.length,
+    };
+}
+// ---------------------------------------------------------------------------------------------------
+// alignEventWindows
+// ---------------------------------------------------------------------------------------------------
+const ALIGN_KEYS = ['events', 'returnObservations', 'eventWindow', 'sessionPolicy'];
+/**
+ * The alignment step of {@link eventStudy} alone: per event, the anchor session and the resolved
+ * event-window rows, or the exclusion reason. Runs the SAME anchoring code path as `eventStudy` —
+ * there is exactly one implementation of the session-policy rules in this module.
+ */
+export function alignEventWindows(input) {
+    const functionName = 'alignEventWindows';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ALIGN_KEYS);
+    requireEvents(functionName, input.events);
+    requireReturnObservations(functionName, 'returnObservations', input.returnObservations);
+    requireSessionWindow(functionName, 'eventWindow', input.eventWindow);
+    const sessionPolicy = resolveEnumOption(functionName, 'sessionPolicy', input.sessionPolicy, SESSION_POLICIES, 'next-session');
+    const sessionsByInstrument = buildInstrumentSessions(functionName, input.returnObservations);
+    const excludedEvents = [];
+    const alignments = [];
+    input.events.forEach((event, index) => {
+        const alignment = alignEventToSessions(functionName, event, `events[${index}]`, sessionsByInstrument, input.eventWindow, sessionPolicy);
+        if (!alignment.ok) {
+            excludedEvents.push({ eventId: event.eventId, reason: alignment.reason });
+            return;
+        }
+        alignments.push({
+            eventId: event.eventId,
+            instrumentId: event.instrumentId,
+            anchorTradingSessionDate: alignment.anchorTradingSessionDate,
+            rows: alignment.rows,
+        });
+    });
+    return {
+        assumptions: {
+            sessionPolicy,
+            eventWindow: {
+                startTradingSessionOffset: input.eventWindow.startTradingSessionOffset,
+                endTradingSessionOffset: input.eventWindow.endTradingSessionOffset,
+            },
+        },
+        diagnostics: {
+            warnings: [],
+            eventsSupplied: input.events.length,
+            eventsAligned: alignments.length,
+            excludedEvents,
+        },
+        alignments,
+    };
+}
+//# sourceMappingURL=events.js.map